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Preface 



Java™ Card™ technology combines a subset of the Java programming language with a 
runtime environment optimized for smart cards and similar small-memory embedded 
devices. The goal of Java Card technology is to bring many of the benefits of Java software 
programming to the resource-constrained world of devices like smart cards. 

The Java Card platform is defined by three specifications: this Java Card Virtual Machine 
Specification, the Java Card 2.1 Application Programming Interface, and the Java Card 
Runtime Environment (JCRE) 2.1 Specification. 

This specification describes the required behavior of the Java Card 2.1 Virtual Machine 
(VM) that developers should adhere to when creating an implementation. An implementation 
within the context of this document refers to a licensee's implementation of the Java Card 
Virtual Machine (VM), Application Programming Interface (API), Converter, or other 
component, based on the Java Card technology specifications. A Reference Implementation 
is an implementation produced by Sun Microsystems, Inc. Programs written for the Java 
Card platform are referred to as Java Card applets. 

Who Should Use This Specification? 

This document is for licensees of the Java Card technology to assist them in creating an 
implementation, developing a specification to extend the Java Card technology 
specifications, or in creating an extension to the Java Card Runtime Environment (JCRE). 
This document is also intended for Java Card applet developers who want a greater 
understanding of the Java Card technology specifications. 



Preface xi 



Before You Read This Specification 

Before reading this document, you should be familiar with the Java programming language, 
the Java Card technology specifications, and smart card technology. A good resource for 
becoming familiar with Java technology and Java Card technology is the Sun Microsystems, 
Inc. website, located at: http://java.sun.com. 



How This Book Is Organized 

Chapter 1, "Introduction," provides an overview of the Java Card Virtual Machine 
architecture. 

Chapter 2, "A Subset of the Java Virtual Machine," describes the subset of the Java 
programming language and Virtual Machine that is supported by the Java Card specification. 

Chapter 3, "Structure of the Java Card Virtual Machine," describes the differences 
between the Java Virtual Machine and the Java Card Virtual Machine. 

Chapter 4, "Java Card Naming," describes the basic uses and requirements of link tokens, 
and provides details of how tokens are used during software production and installation. 

Chapter 5, "The Export File," describes the Converter export file used to link code against 
another package. 

Chapter 6, "The Cap File Format," describes the format of the .cap file. 

Chapter 7, "Instruction Set," describes the byte codes (opcodes) that comprise the Java 
Card Virtual Machine instruction set. 

Chapter 8, "Tables of Instructions," summarizes the Java Card VM instructions in two 
different tables: one sorted by Opcode Value and the other sorted byMnemonic. 

Glossary is a list of words and their definitions to assist you in using this book. 
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Prerequisites 



This specification is not intended to stand on its own; rather it relies heavily on existing 
documentation of the Java platform. In particular, two books are required for the reader to 
understand the material presented here. 

[1] Gosling, James, Bill Joy, and Guy Steele. The Java™ Language Specification. Addison- 
Wesley, 1996, ISBN 0-201-63451-1 - contains the definitive definition of the Java 
programming language. The Java Card 2.1 language subset defined here is based on the 
language specified in this book. 

[2] Lindholm, Tim, and Frank Yellin. The Java™ Virtual Machine Specification. Addison- 
Wesley, 1996, ISBN 0-201-63452-X - defines the standard operation of the Java Virtual 
Machine. The Java Card virtual machine presented here is based on the definition specified 
in this book. 



Related Documents 

References to various documents or products are made in this manual. You should have the 
following documents available: 

• Java Card 2. 1 Application Programming Interface, Draft 2 Revision 1 .4, Sun Micro- 
systems, Inc. 

Java Card Runtime Environment (JCRE) 2.1 Specification Draft 1 Revision 1.2, Sun 
Microsystems, Inc. 

Java Card Applet Developer's Guide, Sun Microsystems, Inc. 

The Java Language Specification by James Gosling, Bill Joy, and Guy L. Steele. Addi- 
son-Wesley, 1996, ISBN 0-201-63451-1. 

The Java Virtual Machine Specification (Java Series) by Tim Lindholm and Frank 
Yellin. Addison-Wesley, 1996, ISBN 0-201-63452-X. 

The Java Class Libraries: An Annotated Reference (Java Series) by Patrick Chan and 
Rosanna Lee. Addison-Wesley, ISBN: 0201634589. 

ISO 78 1 6 Specification Parts 1 -6. 

EMV '96 Integrated Circuit Card Specification for Payment Systems. 



xiii 



Ordering Sun Documents 



The SunDocs SM program provides more than 250 manuals from Sun Microsystems, Inc. If 
you live in the United States, Canada, Europe, or Japan, you can purchase documentation 
sets or individual manuals using this program. 

For a list of documents and how to order them, see the catalog section of the SunExpress T 
Internet site at http://www.sun.com/sunexpress. 



What Typographic Changes Mean 

The following table describes the typographic changes used in this book. 



TABLE P-1 Typographic Conventions 



Typeface or 
Symbol 


Meaning 


Example 


AaBbCcl23 


The names of commands, files, and 
directories; on-screen computer 
output 


Edit your . login file. 
Use Is -a to list all files. 
machine_name% You have mail. 


AaBbCcl23 


What you type, contrasted with on- 
screen computer output 


machine_name% su 
Password: 


AaBbCcJ23 


Command-line placeholder: 
replace with a real name or value 


To delete a file, type rm filename. 


AaBbCcl23 


Book titles, new words or terms, or 
words to be emphasized 


Read Chapter 6 in User's Guide. These are 

called class options. 

You must be root to do this. 
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CHAPTER 1 



Introduction 



1 . 1 Motivation 

Java Card technology enables programs written in the Java programming language to be run 
on smart cards and other small, resource-constrained devices. Developers can build and test 
programs using standard software development tools and environments, then convert them 
into a form that can be installed onto a Java Card enabled device. Application software for 
the Java Card platform is called an applet, or more specifically, a Java Card applet or card 
applet (to distinguish it from browser applets). 

While Java Card technology enables programs written in the Java programming language to 
run on smart cards, such small devices are far too under-powered to support the full 
functionality of the Java platform. Therefore, the Java Card platform supports only a 
carefully chosen, customized subset of the features of the Java platform. This subset provides 
features that are well-suited for writing programs for small devices, and preserves most of 
the "feel" and all of the object-oriented capabilities of the Java programming language. 

A simple approach to specifying a Java Card Virtual Machine would be to describe the 
subset of the features of the Java Virtual Machine that must be supported to allow for 
portability of source code across all Java Card enabled devices. Combining that subset 
specification and the information in the Java Virtual Machine Specification, smart card 
manufacturers could construct their own Java Card implementations. While that approach is 
feasible, it has a serious drawback. The resultant platform would be missing the important 
feature of binary portability of Java Card applets. 

The standards that define the Java platform allow for binary portability of Java programs 
across all Java platform implementations. This "write once, run anywhere" quality of Java 
programs is perhaps the most significant feature of the platform. Part of the motivation for 
the creation of the Java Card platform was to bring just this kind of binary portability to the 
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smart card industry. In a world with hundreds of millions or perhaps even billions of smart 
cards with varying processors and configurations, the costs of supporting multiple binary 
formats for software distribution could be overwhelming. 

This Java Card Virtual Machine Specification is the key to providing binary portability. One 
way of understanding what this specification does is to compare it to its counterpart in the 
Java platform. The Java Virtual Machine Specification defines a Java Virtual Machine as an 
engine that loads Java class files and executes them with a particular set of semantics. The 
class file is a central piece of the Java architecture, and it is the standard for the binary 
compatibility of the Java platform. The Java Card Virtual Machine specification also defines 
a file format that is the standard for binary compatibility for the Java Card platform: the CAP 
file format is the form in which software is loaded onto Java Card enabled devices. 
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1 .2 The Java Card Virtual Machine 

The role of the Java Card Virtual Machine is best understood in the context of the process for 
production and deployment of Java jCard software. There are several components that make 
up a Java Card system, including the Java Card Virtual Machine, the Java Card Converter, an 
off-card installation tool, and an on-card installation program, as shown in Figures 1-1 
and 1-2. 




FIGURE 1-1 Java Card Applet Conversion and Distribution 
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FIGURE 1-2 Java Card Applet Distribution and Installation 



Development of a Java Card applet begins as with any other Java program: a developer 
writes one or more Java classes, and compiles the source code with a Java compiler, 
producing one or more class files. The applet is run, tested and debugged on a workstation 
using simulation tools to emulate the on-card environment. Then, when an applet is ready to 
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be downloaded to a Java Card enabled device, the class files comprising the applet are 
converted to a CAP (converted applet) file using a Java Card Converter. The Java Card 
Converter takes as input not only the class files to be converted, but also one or more 
export files. An export file contains naming information for the contents of other packages 
that are imported by the classes being converted. 

After conversion, the CAP file is copied to a card terminal, such as a desktop computer with 
a card reader peripheral. Then an installation tool on the terminal loads the CAP file and 
transmits it to the Java Card enabled device. An installation program on the Java Card 
enabled device receives the contents of the CAP file and prepares the applet to be run by the 
Java Card Virtual Machine. The virtual machine itself need not load or manipulate CAP 
files; it need only execute the applet code found in the CAP file that was loaded onto the 
card by the on-card installation program. 

The division of functionality between the Java Card Virtual Machine and the on-card 
installation program keeps both the virtual machine and the installation program small. The 
installation program can be implemented as a Java program and executed on top of the Java 
Card Virtual Machine. Since Java Card instructions are denser than typical machine code, 
this reduces the size of the installer. The modularity also allows different installers to be used 
with a single Java Card Virtual Machine implementation. 



Java Language Security 

• 

One of the fundamental features of the Java Virtual Machine is the strong security provided 
in part by the class file verifier. Many Java Card enabled devices may be too small to 
support on-card verification of CAP files. This consideration led to a design that enables on- 
card verification but does not rely on it. The data in a CAP file that is needed only for 
verification is packaged separately from the data needed for the actual execution of its applet. 
This allows for flexibility in how security is managed on a Java Card enabled device. 

There are several options for providing language-level security on a Java Card enabled 
device. The conceptually simplest is to verify the contents of a CAP file on the card as it is 
downloaded or after it is downloaded. This option might only be feasible in the largest of 
Java Card enabled devices. However, some subset of verification might be possible even on 
smaller devices. Other options rely on some combination of one or more of: physical security 
of the installation terminal, a cryptograph ically enforced chain of trust from the source of the 
CAP file, and off-card verification of the contents of a CAP file. 

The Java Card platform standards say as little as possible about CAP file installation and 
security policies. Since smart cards must serve as secure processors in many different 
systems with different security requirements, it is necessary to allow a great deal of 
flexibility to meet the needs of smart card issuers and users. 
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Java Card Runtime Environment Security 



The standard runtime environment for the Java Card platform is the Java Card Runtime 
Environment (JCRE). The JCRE consists of the Java Card Virtual Machine along with the 
Java Card API classes. While the Java Card Virtual Machine has responsibility for ensuring 
Java language-level security, the JCRE imposes additional runtime security requirements on 
Java Card enabled devices which implement the JCRE, which results in a need for additional 
features on the Java Card Virtual Machine. Throughout this document, these additional 
features are designated as JCRE-specific, as shown in the example below. 

The basic runtime security feature imposed by the JCRE enforces isolation of applets using 
what is called an applet firewall The applet firewall prevents the objects that were created 
by one applet from being used by another applet. This prevents unauthorized access to both 
the fields and methods of class instances, as well as the length and contents of arrays. 

Isolation of applets is an important security feature, but it requires a mechanism to allow 
applets to share objects in situations where there is a need to interoperate. The JCRE allows 
such sharing using the concept of sharable interface objects. These objects are the only way 
an applet can make its objects available for use by other applets. For more information about 
using sharable interface objects, see the description of the 

j avacard . framework . Sharable interface in the Java Card API Specification. Some 
descriptions of firewall-related features will make reference to the Sharable interface. 

The applet firewall also protects from unauthorized use the»objects owned by the JCRE itself. 
The JCRE can use mechanisms not reflected in the Java Card API to make its objects 
available for use by applets. A full description of the JCRE-related isolation and sharing 
features can be found in the Java Card Runtime Environment Specification. 
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CHAPTER 2 



A Subset of the Java Virtual Machine 



This chapter describes the subset of the Java virtual machine and language that is supported 
in the Java Card 2.1 platform. 



2. 1 Why a Subset is Needed 

It would be ideal if programs for smart cards could be written using all of the Java 
programming language, but a full implementation of the Java virtual machine is far too large 
to fit on even the most advanced memory-constrained devices available today. 

A typical memory-constrained device has less than IK of RAM and 16K of ROM. The code 
for implementing string manipulation, single and double-precision floating point arithmetic, 
and thread management would be larger than the ROM space on such a device. Even if it _ 
could be made to fit, there would be no space left over for class libraries or application code. 
RAM resources are also very limited. The only workable option is to implement Java Card as 
a subset of the Java platform. 



2.2 Java Card Language Subset 

Implementations and applets written for the Java Card platform are written in the Java 
. programming language. They are compiled using Java compilers. Java Card technology uses 
a subset of the Java language, and familiarity with the Java platform is required to 
understand the Java Card platform. 

The items discussed in this section are not described to the level of a language specification. 
For complete documentation on the Java programming language, The Java Language 
Specification. (§1.1) 
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2.2.1 



Unsupported Items 



The items listed in this section are elements of the Java programming language and platform 
that are not supported by the Java Card platform. 



2.2.1.1 Unsupported Features 
Dynamic Class Loading 

Dynamic class loading is not supported in the Java Card platform. An implementation of the 
Java Card platform is not able to load classes dynamically. Classes are either masked into the 
card during manufacturing or downloaded through an installation process after the card has 
been issued. Programs executing on the card may only refer to classes that already exist on 
the card, since there is no way to download classes during the normal execution of 
application code. 



Security Manager 

Security management in the Java Card platform differs significantly from that of the Java 
platform. In the Java platform, there is a Security Manager class (java.lang.SecurityManager) 
responsible for implementing security features. In the Java Card platform, language security 
policies are implemented by the Virtual Machine. There is no Security Manager class that 
makes policy decisions on whether to allow operations. 



Garbage Collection & Finalization 

Java Card does not require a garbage collector. Nor does Java Card allow explicit 
deallocation of objects, since this would break Java programming language's required 
pointer- safety. Therefore, application programmers may not assume that objects that are 
allocated are ever deallocated. Storage for unreachable objects will not necessarily be 
reclaimed. 

Finalization is also not required, finalize ( ) will not necessarily be called automatically 
by the Java Card virtual machine, and programmers should not rely on this behavior. 



Threads 

The Java Card virtual machine does not support multiple threads of control. Neither class 
Thread nor any of the thread-related keywords can be used in implementations of the Java 
Card platform. 
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Cloning 



The Java Card platform does not support cloning of objects, Java Card API class Object 
does not implement a clone () method, and there is no Clonable interface provided. 



Access Control in Java Packages 

The Java Card language subset supports the package access control defined in the Java 
language. However, there are two cases that are not supported. 

n If a class implements a method with package access visibility, a subclass may not 
override the method and change the access visibility of the. method to protected or 
public. 

n An interface that is defined with package access visibility may not be extended by an 
interface with public access visibility. 



2.2.1.2 Keywords 

The following keywords indicate unsupported options related to threads or memory 
management. 

synchronized transient volatile 



2.2. 1 .3 Unsupported Types 

The Java Card platform does not support types char, double, float or long,* or 
operations on those types. It also does not support arrays with more than one dimension. 



2.2.1.4 Classes 

In general, none of the Java classes are supported in the Java Card platform. Some classes 
from the j ava . lang package are supported (see Section 2.2.2.4, "Classes), but none of the 
rest are. For example, classes that are not supported are String, Thread (and all thread- 
related classes), wrapper classes such as Boolean and Integer, and class Class. 



System 

Class j ava . lang . System is not supported. Java Card supplies a class 

javacard. framework. JCSystem, which provides an interface to system behavior. 
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2.2.2 Supported Items 

If a language feature is not explicitly described as unsupported, it is part of the supported 
subset. Notable supported features are described in this section. 



2.2.2.1 Features 



Packages 

Implementations and applets written for the Java Card platform follow the standard rules for 
the Java platform packages. Java Card API classes are written as j ava source files, which 
include package designations. Package mechanisms are used to identify and control access to 
classes, static fields and static methods. Except as noted in "Access Control in Java 
Packages" on page 9, packages in the Java Card platform are used exactly the way they are 
in the Java platform. 

Dynamic Object Creation 

The Java Card platform programs supports dynamically created objects, both class instances 
and arrays. This is done, as usual, by using the new operator. Objects are allocated out of the 
heap. 

As noted in "Garbage Collection & Finalization" on page 8, a Java Card Virtual Machine 
will not necessarily garbage collect objects. Any objects allocated on the card may continue 
to exist and consume resources even after they become unreachable. 



Virtual Methods 

Since Java Card objects are Java programming language objects, invoking virtual methods on 
objects in a program written for the Java Card platform is exactly the same as in a program 
written for the Java platform. Inheritance is supported, including the use of the super 
keyword. 



Interfaces 

Java Card classes may define or implement Interfaces as in the Java programming language. 
Invoking virtual methods on interface types works as expected. Type checking and the 
instanceof operator also work correctly with interfaces. 
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Exceptions 

Java Card programs may define, throw and catch exceptions, as in Java programs. Class 
Throwable and its relevant subclasses are supported. (Some Exception and Error 
subclasses are omitted, since those exceptions cannot occur in the Java Card platform. See 
Section 2.3.3, "Exceptions" for specification of errors and exceptions.) 



2.2.2.2 Keywords 

The following keywords are supported. Their use is the same as in the Java programming 
language. 



abstract 


default 


If 


package 


switch 


boolean 


do 


implements 


private 


this 


break 


else 


import 


protected 


throw 


byte 


extends 


instanceof 


public 


throws 


case 


final 


int 


return 


try 


catch 


finally 


interface 


short 


void 


class 


for 


native 


static 


while 


continue 


goto 


new 


super 





2.2.2.3 Types 

Java programming language types boolean, byte, short, and int are supported. Objects 
(class instances and single-dimensional arrays) are also supported. Arrays can contain the 
supported primitive data types, objects, and other arrays. 

Some Java Card implementations might not support use of the int data type. (Refer to 
Section 2.2.3.1, "int.") 



2.2.2.4 Classes 



Most of the classes in the java. lang package are not supported in Java Card. The 
following classes from java . lang are supported on the card in a limited form. 



Object 

Java Card classes descend from java. lang. Object, just as in the Java programming 
language. Most of the methods of Object are not available in the Java Card API, but the 
class itself exists to provide a root for the class hierarchy. 
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Throwable 



Class Throwable and its subclasses are supported. Most of the methods of Throwable are 
not available in the Java Card API, but the class itself exists to provide a common ancestor 
for all exceptions. 



2.2.3 Optionally Supported Items 



This section describes what items are optionally supported. Optional means that a Java Card 
implementation is not required to support the specified items. 

Optional features of the Java programming language are optional in the Java Card platform 
or not required for a Java Card compatible implementation. These features are described 
below. 



2.2.3.1 int 



The int keyword and 32-bit integer data types need not be supported in a Java Card 
implementation. A Java Card Virtual Machine that does not support the int data type will 
reject programs using that type. 



2.2.4 Limitations of the Java Card Virtual Machine 

The limitations of card hardware prevent Java Card programs from supporting the full range 
of functionality of certain Java platform features. The features in question are supported, but 
a particular virtual machine may limit the range of operation to less than that of the Java 
platform. 

To ensure a level of portability for application code, this section establishes a minimum 
required level for partial support of these language features. 

The limitations here are listed as maximums from the application programmer's perspective. 
Applets that do not violate these maximum values will be portable across all Java Card 
implementations. From the Java Card VM implemented perspective, each maximum listed 
indicates a minimum level of support that will allow portability of applets. 
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Objects 



Methods 

A class can implement a maximum of 128 public or protected instance methods, and a 
maximum of 128 instance methods with package visibility. These limits include inherited 
methods. 



Class Instances 

Class instances can contain a maximum of 256 fields, where an int data type is counted as 
occupying two fields. 



Arrays 

Arrays can hold a maximum of 32767 fields. 



Methods 

The maximum size of a stack frame is 127 words, where an int data type is counted as 
occupying two words. This includes the parameters, locals, and operand stack. 



Switch Statements 

Java Card programs are limited to a maximum of 65536 cases in a switch statement. 

Class Initialization 

There is limited support for initialization of static field values in <clinit> methods. Static 
fields of applets may only be initialized to primitive compile-time constant values, or arrays 
of primitive compile-time constants. Static fields of user libraries may only be initialized to 
primitive compile-time constant values. Primitive constant data types include boolean, 
byte, short, and int. 
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2.3 



Java Card VM Subset 



Java Card technology uses a subset of the Java Virtual Machine, and familiarity with the 
Java platform is required to understand the Java Card Virtual Machine. 

The items discussed in this section are not described to the level of a virtual machine 
specification. For complete documentation on the Java Virtual Machine, refer to §1.1 of The 
Java™ Virtual Machine Specification. 



2.3. 1 class File Subset 

The Java Card Virtual Machine operates on standard Java platform class files. Since the 
Java Card Virtual Machine supports only a subset of the behavior of the Java Virtual 
Machine, it also supports only a subset of the standard class file format. 



2.3.1.1 Not Supported in Class Files 



Field Descriptors 

Field descriptors may not contain BaseType characters C, D, F or L. ArrayType descriptors 
for arrays of more than one dimension may not be used. 



Constant Pool 

Constant pool table entry tags that indicate unsupported types are not supported. 
TABLE 2-1 Unsupported constant pool tags 



Constant Type Value 

CONSTANT_String ~S 

CONSTANT_Float 4 

CONSTANT_Long 5 

CONSTANT Double 6 



Constant pool structures for types CONSTANT_String_inf o, CONSTANT_Float_inf o, 
CONSTANT_Long_inf o and CONS TAN T_Double_inf o are not supported. 
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Fields 



In f ield_info structures, the access flags ACC_VOLATILE and ACC_TRANSIENT are not 
supported. , 

Methods 

In method_inf o structures, the access flags ACC_SYNCHRONIZED and ACC_NATIVE are 
not supported. 

Supported in Class Files 
ClassFile 

All items in the ClassFile structure are supported. 
Field Descriptors 

Field descriptors may contain BaseType characters B, I, S and Z, as well as any ObjectType. 
ArrayType descriptors for arrays of a single dimension may also be used. 

Method Descriptors 

All forms of method descriptors are supported. 

Constant pool 

Constant pool table entry tags for supported data types are supported. 
table 2-2 Supported constant pool tags. 



Constant Type Value 

CONSTANT_Class 7 

CONSTANT_Fieldref 9 

CONSTANT_Me thodre f 10 
CONSTANT_InterfaceMethodref 11 

CONSTANT_Integer 3 

CONSTANT J^ameAndType 12 

CONSTANT Utf8 1 
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Constant pool structures for types CONSTANT_Class_inf o, CONSTANT_Fieldref_inf o, 
CONSTANT_Methodref_info, CONSTANT_Interf aceMethpdref_inf o, 
CONSTANT_Integer_info, CONSTANT_NameAndType_inf o and 
CON S T ANT_U t f 8_i n f o are supported. 



Fields 

In f ield_info structures, the supported access flags are ACC_PUBLIC, ACC_PRIVATE, 
ACC_PROTECTED, ACC_STATIC and ACC_FINAL. 

The remaining components of f ield_inf o structures are fully supported. 



Methods 

In method_inf o structures, the supported access flags are ACC_PUBLIC, ACC_PRIVATE, 
ACC_PROTECTED, ACC_STATIC, ACC_FINAL and ACC_ABSTRACT. The access flag 
ACC_NATIVE is supported for non-applet class files. 

The remaining components of method_inf o structures are fully supported. 



Attributes 

The attribute_info structure is supported. The Code, ConstantValue, Exceptions 
and LocalVariableTable attributes are supported. 



2.3.2 Bytecode Subset 

The following sections detail the bytecodes that are either supported or unsupported in the 
Java Card platform. For more details, refer to Chapter 6, "Instruction Set." 
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2.3.2.1 



Unsupported Bytecodes 



lconst_<l> 


fconst_<f> 


dconst_<d> 


Idc2_w2 


lload 


fload 


dload 


lload_<n> 


fload_<n> 


dload_<n> 


laload 


faload 


daload 


caload 


lstore 


fstore 


dstore 


lstore_<n> 


fstore_<n> 


dstore_<n> 


lastore 


fastore 


dastore 


castore 


ladd 


fadd 


dadd 


lsub 


fsub 


dsub 


lmul 


fmul 


dmul 


ldiv 


fdiv 


ddiv 


lreiti 


f rem 


drem 


lneg 


fneg 


dneg 


lshl 


lshr 


lushr 


land 


lor 


Ixor 


i21 


i2f 


i2d 


12i 


12f 


12d 


f2i 


f2d 


d2i 


d21 


d2f 


i2c 


lcmp 


f cmpl 


fcmpg 


dcmpl 


dcmpg 


lreturn 


f return 


dreturn 


monitorenter 


monitorexit 


mult iane war ray 


goto w 


jsr_w 









2.3.2.2 Supported Bytecodes 



nop 


aconst__null 


iconst <i> 


bipush 


sipush 


ldc 


ldc_w 


iload 


aload 


iload_<n> 


aload_<n> 


iaload 


aaload 


baload 


saload 


istore 


astore 


istore__<n> 


astore_<n> 


iastore 


aastore 


bastore 


sastore 


pop 


pop2 


dup 


dup_xl 


dup_x2 


dup2 


dup2_xl 


dup2_x2 


swap 


iadd 


isub 


imul 


idiv 


irem 


ineg 


ior 


ishl 


ishr 


iushr 


iand 


ixor 


iinc 


i2b 


i2s 


if <cond> 


if icmp_<cond> 


ifacmp_<cond> 


goto 


jsr 


ret 


tableswitch 


lookupswitch 


ireturn 


areturn 


return 


getstatic 


putstatic 


getf ield 


putf ield 


invokevirtual 


invokespecial 
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invokestatic 



invokeinterf ace 



new 



newarray 
checkcast 



anewarray 
instanceof 



arraylength 
wide 



athrbw 



ifnull 



if nonnull 



Static Restrictions on Bytecodes 

For it to be acceptable to a Java Card Virtual Machine, a class file must conform to the 
following restrictions on the static form of bytecodes. 

Idc, ldc_w 

The ldc and ldc_w bytecodes can only be used to load integer constants. The constant pool 
entry at index must be a CONSTANT_Integer entry. 

lookupswitch 

The value of the npairs operand must be less than 65536. The bytecode can contain at most 
65535 cases. 

tableswitch 

The values of the high and low operands must both be less than 65536 (so they can fit in 16 
bits). The bytecode can contain at most 65535 cases. 



The wide bytecode cannot be used to generate local indices greater than 127, and it cannot 
be used with any instructions other than iinc. It can only be used with an iinc bytecode to 
extend the range of the increment constant. 



Java Card provides full support for the Java platform's exception mechanism. Users can 
define, throw and catch exceptions just as in the Java platform. Java Card also makes use of 
the exceptions and errors defined in The Java Language Specification [1]. An updated list of 
the Java platform's exceptions is provided in the JDK documentation. 



wide 



Exceptions 



Java Card Virtual Machine 2.1 Specification • January 29, 1999 



Not all of the Java platform's exceptions are supported in Java Card. Exceptions related to 
unsupported features are naturally not supported. Class loader exceptions (the bulk of the 
checked exceptions) are not supported. And no exceptions or errors defined in packages 
other than java . lang are supported. 

Note that some exceptions may be supported to the extent that their error conditions are 
detected correctly, but classes for those exceptions will not necessarily be present in the API. 

The supported subset is described in the tables below. 



Uncaught and Uncatchable Exceptions 

In the Java platform, uncaught exceptions and errors will cause the virtual machine to report 
the error condition and exit. In Java Card, uncaught exceptions or errors should cause the 
Virtual Machine to halt. Optionally, an implementation can require the card to be muted or 
blocked from further use. 

Throwing a runtime exception or error that cannot be caught should also cause the card to be 
muted. Cards may also optionally take stricter actions in response to throwing such an 
exception. 



Checked Exceptions 

table 2-3 Support of checked exceptions 



Exception 


Supported 


Not Supported 


ClassNotFoundException 






CloneNot Support edExcept ion 






IllegalAccessException 






InstantiationException 






Interrupt edExcept ion 






NoSuchFieldExcept ion 






NoSuchMethodExcept ion 
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2.3.3.3 Runtime Exceptions 

table 2-4 Support of runtime exceptions 



Runtime Exception 


Supported 


Not Supported 


A rifrVim^tippYPPT^tifvn 






rVIT ay O lUICCf A.CCp 11UL1 






{** 1 a c c f^a c tT* v r* pt*\ri fin 
V^laSaV^aoLCACCpUUll 






IllegalArgumentException 


• 




IllegalThreadStateException 




• 


NumberFormatException 




• 


IllegalMonitorStateException 




• 


IllegalStateException 


• 




IndexOutOfBoundsException 


• 




AnaylndexOutOfBoundsException 


• 




StringlndexOutOfBoundsException 




• 


NegativeArraySizeException 


• 




NullPointerException 


• 




SecurityException 


• 





2.3.3.4 Errors 

TABLE 2-5 Support of errors 



Error 


Supported 


Not Supported 


LinkageError 






ClassCircularityError 






ClassFormatError 






ExceptionlnlnitializerError 






IncompatibleClassChangeError 






AbstractMethodError 






IllegalAccessError 






InstantiationError 






NoSuchFieldError 






NoSuchMethodError 






NoClassDefFoundError 






UnsatisfiedLinkError 
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Error 


Supported 


Not Supported 


VerifyError 


• 




ThreadDeath 




• 


VirtualMachineError 






IntemalError 






OutOfMemoryError 






StackOverflowError 






UnknownError 
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Structure of the Java Card Virtual 
Machine 



The specification of the Java Card Virtual Machine is in many ways quite similar to that of 
the Java Virtual Machine. This similarity is of course intentional, as the design of the Java 
Card Virtual Machine was based on that of the Java Virtual Machine. Rather than reiterate all 
the details of this specification which are shared with that of the Java Virtual Machine, this 
chapter will mainly refer to its counterpart in the Java Virtual Machine Specification, 
providing new information only where the Java Card Virtual Machine differs. 



The Java Card Virtual Machine supports the same two kinds of data types as the Java Virtual 
Machine: primitive types and reference types. Likewise, the same two kinds of values are 
used: primitive values and reference values. 

The primitive data types supported by the Java Card Virtual Machine are the numeric types 
and the returnAddress type. The numeric types consist only of the integral types: 

n byte, whose values are 8-bit signed two's complement integers 
n short, whose values are 16-bit signed two's complement integers 

Some Java Card Virtual Machine implementations may also support an additional integral 
type: 

n int, whose values are 32-bit signed two's complement integers 

Support for reference types is identical to that in the Java Virtual Machine. 



3.1 
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Words 



The Java Card Virtual Machine is defined in terms of an abstract storage unit called a word. 
This specification does not mandate the actual size in bits of a word on a specific platform. 
A word is large enough to hold a value of type byte, short, reference or 
returnAddress. Two words are large enough to hold a value of type int. 

The actual storage used for values in an implementation is platform-specific. There is enough 
information present in the descriptor component of a CAP file to allow an implementation to 
optimize the storage used for values in variables and on the stack. 



The Java Card Virtual Machine can support only a single thread of execution. Any runtime 
data area in the Java Virtual Machine which is duplicated on a per-thread basis will have 
only one global copy in the Java Card Virtual Machine. 

The Java Card Virtual Machine's heap is not required to be garbage collected. Objects 
allocated from the heap will not necessarily be reclaimed. 

This specification does not include support for native methods, so there are no native 
method stacks. 

Otherwise, the runtime data areas are as documented for the Java Virtual Machine. 



Each applet running on a Java Card Virtual Machine is associated with an execution context 
known as an applet context. The Java Card Virtual Machine uses the applet context of the 
current frame to enforce security policies for inter-applet operations. 

There is a one-to-one mapping between applet contexts and packages in which applets are 
defined. An easy way to think of an applet context is as the runtime equivalent of a package, 
since Java packages are compile-time constructs and have no direct representation at runtime. 
As a consequence, all applets managed by applet instances of applet classes from the same 
package will share the same applet context. 

The Java Card Runtime Environment also has its own applet context. Framework objects 
execute in this JCRE context. 



3.3 



Runtime Data Areas 



3.4 



Applet Contexts 
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The applet context of the currently executing method is known as the current context. When 
a method in one context successfully invokes a method in another context, the Java Card 
Virtual Machine performs an applet context switch. Afterwards the invoked method's applet 
context becomes the current context. When the invoked method returns, the current context is 
switched back to the previous context. 



Frames 

Java Card Virtual Machine frames are very similar to those defined for the Java Virtual 
Machine. Each frame has a set of local variables and an operand stack. Frames also contain 
a reference to a constant pool, but since all constant pools for all classes in a package are 
merged, the reference is to the constant pool for the current class* package. 

Each frame also includes a reference to the applet context in which the current method is 
executing. 



Representation of Objects 

The Java Card Virtual Machine does not mandate a particular internal structure for objects or 
a particular layout of their contents. However, the core components in a CAP file are defined 
assuming a default structure for certain runtime structures (such as descriptions of classes), 
and a default layout for the contents of dynamically allocated objects. Information from the 
descriptor component of the CAP file can be used to format objects in whatever way an 
implementation requires. 



Special Initialization Methods 

The Java Card Virtual Machine supports instance initialization methods exactly as does the 
Java Virtual Machine. 

The Java Card Virtual Machine includes only limited support for class or interface 
initialization methods. There is no general mechanism for executing <clinit> methods on 
a Java Card Virtual Machine. Instead, a CAP file includes information for initializing class 
data as defined in Chapter 2, "A Subset of the Java Virtual Machine." 
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3.8 Exceptions 



Exception support in the Java Card Virtual Machine is identical to support for exceptions in 
the Java Virtual Machine. 



This specification defines two binary file formats which enable platform-independent 
development, distribution and execution of Java Card software. 

The CAP file format describes files that contain executable code and can be downloaded and 
installed onto a Java Card enabled device. A CAP file is produced by a Java Card Converter 
tool, and contains a converted form of an entire package of Java classes. This file format's 
relationship to the Java Card Virtual Machine is analogous to the relationship of the class 
file format to the Java Virtual Machine. 

The export file format describes files that contain the public linking information of Java Card 
packages. A package's export file is used when converting client packages of that package. 



The Java Card Virtual Machine instruction set is quite similar to the Java Virtual Machine 
instruction set. Individual instructions consist of a one-byte opcode and zero or more 
operands. The pseudo-code for the Java Card Virtual Machine's instruction fetch-decode- 
execute loop is the same. And multi-byte operand data is also encoded in big-endian order. 

There are a number of ways in which the Java Card Virtual Machine instruction set diverges 
from that of the Java Virtual Machine. Most of the differences are due to the Java Card 
Virtual Machine's more limited support for data types. Another source of divergence is that 
the Java Card Virtual Machine is intended to run on 8-bit and 16-bit architectures, whereas 
the Java Virtual Machine was designed for a 32-bit architecture. The rest of the differences 
are all oriented in one way or another toward optimizing the size or performance of either the 
Java Card Virtual Machine or Java Card programs. These changes include inlining constant 
pool data directly in instruction opcodes or operands, adding multiple versions of a particular 
instruction to deal with different datatypes, and creating composite instructions for 
operations on the current object. 





3.10 



Instruction Set Summary 
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3.10.1 



Types and the Java Card Virtual Machine 



The Java Card Virtual Machine supports only a subset of the types supported by the Java 
Virtual Machine, this subset is described in Chapter 2, "A Subset of the Java Virtual 
Machine." Type support is reflected in the instruction set, as instructions encode the data 
types on which they operate. 

Given that the Java Card Virtual Machine supports fewer types than the Java Virtual 
Machine, there is an opportunity for better support for smaller data types. Lack of support for 
large numeric data types frees up space in the instruction set. This extra instruction space has 
been used to directly support arithmetic operations on the short data type. 

Some of the extra instruction space has also been used to optimize common operations. Type 
information is directly encoded in field access instructions, rather than being obtained from 
an entry in the constant pool. 

TABLE 3-1 summarizes the type support in the instruction set of the Java Card Virtual 
Machine. Only instructions that exist for multiple types are listed. Wide and composite forms 
of instructions are not listed either. A specific instruction, with type information, is built by 
replacing the Tin the instruction template in the opcode column by the letter representing the 
type in the type column. If the type column for some instruction is blank, then no instruction 
exists supporting that operation on that type. For instance, there is a load instruction for type 
short, shad, but there is no load instruction for type byte. 



table 3-1 Type support in the Java Card Virtual Machine Instruction Set 



opcode 


byte 


short 


Int 


reference 


Tspush 


bspush 


sspush 






Tipush 


bipush 


sipush 


iipush 




Tconst 




sconst 


iconst 


aconst 


Tload 




sload 


iload 


aload 


Tstore 




sstore 


istore 


astore 


Tine 




sine 


iinc 




Taload 


baload 


saload 


iaload 


aaload 


Tastore 


bastore 


sastore 


iastore 


aastore 


Tadd 




sadd 


iadd 




Tsub 




ssub 


isub 




Tmul 




smul 


imul 




Tdiv 




sdiv 


idiv 




Trem 




srem 


irem 




Tneg 




sneg 


ineg 
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table 3-1 Type support in the Java Card Virtual Machine Instruction Set 



opcode 


byte 


short 


fnt 


reference 


Tshl 




sshl 


ishl 




Tshr 




sshr 


ishr 




Tushr 




sushr 


iushr 




Tand 




sand 


iand 




Tor 




sor 


ior 




Txor 




sxor 


icor 




s2T 


s2b 




s2i 




i2T 


i2b 


i2s 






Temp 






icmp 




if_TcmpOP 




if_scmpOP 




if_acmpOP 


Tlookupswitch 




slookupswitch 


ilookupswitch 




Ttableswitch 




stableswitch 


itableswitch 




Treturn 




sreturn 


ireturn 


areturn 


getstatic_T 


getstatie_b 


getstatic_s 


getstatic_i 


getstatic_a 


putstatic_T 


putstatic_b 


putstatic_s 


putstatic_i 


putstatic_a 


getfield_T 


getfield_b 


getfield_s 


getfleld_i 


getfield_a 


putfield_T 


putfield_b 


putfield_s 


putfield_i 


putfield_a 



The mapping between Java storage types and Java Card Virtual Machine computational types 
is summarized by the following table: 



table 3-2 Storage types and computational types 



Java (Storage) Type 


Size in 
Bits 


Computational Type 


byte 


8 


short 


short 


16 


short 


int 


32 


int 



Chapter 7, "Java Card Virtual Machine Instruction Set," describes the Java Card Virtual 
Machine instruction set in detail. 
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Java Card Naming 



This chapter describes the mechanisms used for naming items in Java Card CAP files and 
Export files. Java class files use Unicode strings organized with a particular convention to 
name Java packages as well as items within those packages. As the Java Card platform does 
not include support for strings, alternative support for naming is provided. 

This chapter describes a scheme that allows downloaded software to be linked against APIs 
on a Java Card enabled smart card. The scheme represents referenced items as opaque 
tokens, instead of Unicode strings as are used in Java class files. The two basic requirements 
of this linking scheme are that it allows linking on the card, and that it does not require 
internal implementation details of card APIs to be revealed to clients of those APIs. 
Secondary requirements are that the scheme be efficient in terms of resource use on the card, 
and have good performance for linking. And of course, it must preserve the semantics of the 
Java language. 



4. 1 Overview of Token-based Linking 

This section provides an overview of tokens and their roles in the various stages of the 
production and installation of packages which implement applets and user libraries. 



4.1.1 Externally Visible Items 

Classes (including Interfaces) in Java packages may be declared with public or package 
visibility. A class's methods and fields may be declared with public, protected, package or 
private visibility. For purposes of this document, we define public classes, public or 
protected fields, and public or protected methods to be externally visible from the package. 
All externally visible items are described in a package's Export file. 
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Each externally visible item must have a token associated with it to enable references from 
other packages to the item to be resolved on-card. There are six kinds of items in a package 
that require external identification. 

n Classes (including Interfaces) 

n Static Fields 

n Static Methods 

n Instance Fields 

n Virtual Methods 

n Interface Methods 



Private Tokens 

Items which are not externally visible are internally visible. Internally visible items are not 
described in a package's export file, but some such items use private tokens to represent 
internal references. External references are represented by public tokens. There are two kinds 
of items which can be assigned private tokens. 

n Instance Fields 
n Virtual Methods 



The Export File and Conversion 

Each externally visible item in a package has an entry in the package's export file. Each 
entry holds the item's name and its token. Some entries may include additional information 
as well. For detailed information on the export file format, see Chapter 5, "The Export File 
Format." 

The export file is used to map names for imported items to tokens during package 
conversion. 

During the conversion of the class files of applet A, the export file of 

javacard. framework is used to find tokens for items in the API which are used by the 

applet. The Java Card converter uses these tokens to represent references to items in the API. 

For instance, an applet creates a new instance of framework class PIN. The framework 
export file contains an entry for j a vacard. framework. PIN which holds the token for this class. 
The converter places this token in the CAP file's constant pool to represent an unresolved 
reference to the class. The token value is used to resolve the reference on a card. 
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4.1.4 



References - External and Internal 



In the context of a CAP file, references to items are made indirectly through a package's 
constant pool. References to items in other packages are called external, and are represented 
in terms of tokens. References to items in the same CAP file are called internal, and are 
represented either in terms of tokens, or in a different internal format. 

An external reference to a class is composed of a package token and a class token. Together 
those tokens specify a certain class in a certain package. An internal reference to a class is a 
15-bit value which is a pointer to the class structure's location within the CAP file. 

An external reference to a static class member, either a field or method, consists of a package 
token, a class token, and a token for the static field or static method. An internal reference to 
a static class member is a 16-bit value which is a pointer to the item's location in the CAP 
file. 

References to instance fields, virtual methods and interface methods consist of a class 
reference and a token of the appropriate type. The class reference determines whether the 
reference is external or internal. 



4.1.5 Installation and Linking 

External references in a CAP file can be resolved on a card from token form into the internal 
representation used by the card virtual machine. 

A token can only be resolved in the context of the package which defines it. Just as the 
export file maps from a package's externally visible names to tokens, there is a set of link 
information for each package on the card that maps from tokens to resolved references. 



4.2 Token Assignment 

Tokens for an API are assigned by the API's developer and published in the package export 
file(s) for that API. Since the name-to-token mappings are published, an API developer may 
choose any order for tokens (subject to the constraints listed below). 

A particular card platform can resolve tokens into whatever internal representation is most 
useful for that implementation of a Java Card VM. Some tokens may be resolved to indices. 
For example, an instance field token may be resolved to an index into a class instance's 
fields. In such cases, the token value is distinct from and unrelated to the value of the 
resolved index. 
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4.2.1 



Token Details 



Each kind of item in a package has its own independent scope for tokens of that kind. The 
token range and assignment rules for each kind are listed below. 
TABLE 4-1 Token Range, Type and Scope 



Token Type 


Range 


Type 


Scope 


Package 


0 - 127 


Private 


CAP File 


Class 


0-255 


Public 


Package 


Static Field 


0-255 


Public 


Class 


Static Method 


0-255 


Public 


Class 


Instance Field 


0-255 


Public or Private 


Class 


Virtual Method 


0 - 127 


Public or Private 


Class Hierarchy 


Interface Method 


0 - 127 


Public 


Class 



4.2.1.1 Package 

All package references from within a CAP file are assigned private tokens; package tokens 
will never appear in an export file. Package token values must be in the range from 0 to 127, 
inclusive. The tokens for all the packages referenced from classes in a CAP file are 
numbered consecutively starting at zero. The ordering of package tokens is not specified. 



4.2. 1 .2 Classes and Interfaces 

All externally visible classes in a package are assigned public tokens. Package-visible classes 
are not assigned tokens. Class token values must be in the range from 0 to 255, inclusive. 
The tokens for all the public classes in a package are numbered consecutively starting at 
zero. The ordering of class tokens is not specified. 



4.2.1.3 Static Fields 

All externally visible static fields in a package are assigned public tokens. Package-visible 
and private static fields are not assigned tokens. No tokens are assigned for final static fields 
which are initialized to primitive, compile-time constants, as these fields are never linked on- 
card. Static fields token values must be in the range from 0 to 255, inclusive. The tokens for 
all other externally visible static fields in a class are numbered consecutively starting at zero. 
The ordering of static field tokens is not specified. 
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4.2.1.4 



Static Methods 



All externally visible static methods in a package are assigned public tokens, including 
statically bound instance methods such as constructors. Static method token values must be 
in the range from 0 to 255, inclusive. Package-visible and private static methods are not 
assigned tokens. The tokens for all the externally visible static methods in a class are 
numbered consecutively starting at zero. The ordering of static method tokens is not 
specified. 



4.2.1.5 Instance Fields 

All instance fields defined in a package are assigned either public or private tokens. Instance 
field token values must be in the range from 0 to 255, inclusive. Public and private tokens for 
instance fields are assigned from the same namespace. The tokens for all the instance fields 
in a class are numbered consecutively starting at zero, except that the token after an int 
field is skipped and the token for the following field is numbered two greater than the token 
of the int field. Tokens for externally visible fields must be numbered less than the tokens 
for package and private fields. For public tokens, the tokens for reference type fields must be 
numbered greater than the tokens for primitive type fields. For private tokens, the tokens for 
reference type fields must be numbered less than the tokens for primitive type fields. Beyond 
that the ordering of instance field tokens in a class is not specified. 





primitive 


boolean 


0 


public and 
protected 




byte 


1 




short 


2 


public tokens 


references 


byte[] 


3 




Applet 


4 




references 


short[] 


5 


package and 
private 




Object 


6 


primitive 


int 


7 


private tokens 




short 


9 



4.2.1.6 Virtual Methods 

All virtual methods defined in a package are assigned either public or private tokens. Virtual 
method token values must be in the range from 0 to 127, inclusive. Public and private tokens 
for virtual methods are assigned from different namespaces. The high bit of the byte 
containing a virtual method token is set to one if the token is a private token. 

Public tokens for the externally visible introduced virtual methods in a class are numbered 
consecutively starting at one greater than the highest numbered public virtual method token 
of the class's superclass. If a method overrides a method implemented in the class's 
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superclass, that method uses the same token number as the method in the superclass. The 
high bit of the byte containing a public virtual method token is always set to zero, to indicate 
it is a public token. The ordering of public virtual method tokens in a class is not specified. 

Private virtual method tokens are assigned differently from public virtual method tokens. If a 
class and its superclass are defined in the same package, the tokens for the package- visible 
introduced virtual methods in that class are numbered consecutively starting at one greater 
than the highest numbered private virtual method token of the class's superclass. If the class 
and its superclass are defined in different packages, the tokens for the package-visible 
introduced virtual methods in that class are numbered consecutively starting at zero. If a 
method overrides a method implemented in the class's superclass, that method uses the same 
token number as the method in the superclass. The definition of the Java programming 
language specifies that overriding a package-visible virtual method is only possible if both 
the class and its superclass are defined in the same package. The high bit of the byte 
containing a virtual method token is always set to one, to indicate it is a private token. The 
ordering of private virtual method tokens in a class is not specified. 

4.2. 1 .7 Interface Methods 

All interface methods defined in a package are assigned public tokens, as interface methods 
are always public. Interface methods tokens values must be in the range from 0 to 127, 
inclusive. The tokens for all the interface methods defined in or inherited by an interface are 
numbered consecutively starting at zero. The token value for an interface method in a given 
interface is unrelated to the token values of that same method in any of the interface's 
superinterfaces. The high bit of the byte containing an interface method token is always set 
to zero, to indicate it is a public token. The ordering of interface method tokens is not 
specified. 
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CHAPTER 5 



The Export File Format 



This chapter describes the Java Card Virtual Machine Export file format. Compliant Java 
Card Virtual Machines must be capable of producing and consuming all Export files that 
conform to the specification provided in this book. 

A Java Card Export file contains all of the public classes and interfaces defined in one Java 
package, and alt of the public and protected fields and methods defined in those classes and 
interfaces. The Export File contains a mapping of these items to tokens (Chapter 3, "Java 
Card Naming"). Tokens are used to identify items in a CAP file (Chapter 5, "The Cap File 
Format") and resolve references on a Java Card. The Export file is used during conversion of 
a package and creation of a Java Card CAP file. 

The format in the Export file is similar to the Java class file. Structures and data in Java - 
class files that describe internal implementation details, like bytecodes and private methods, 
are not included. Information beyond that in a Java class file includes package identification 
details and tokens associated with each class, interface, field, and method. 

Final static fields of primitive types are represented in the Export file, but are not assigned 
token values suitable for referencing on Java Cards. These fields are not represented in CAP 
files or on Java Cards. Instead Java Card Converters must replace bytecodes that reference 
final static fields of primitive types with bytecodes that load the constant value of the field. 
Having this information included in the Export file enables this Converter functionality. 1 

An Export file consists of a stream of 8-bit bytes. All 16-bit quantities are constructed by 
reading in two consecutive 8-bit bytes. Multibyte data items are always stored in big-endian 
order, where the high-order bytes come first. 

This chapter defines its own set of data types representing Java Card Export file data: The 
types ul, and u2 represent an unsigned one-, and two-byte quantities, respectively. 



1. Although Java compilers ordinarily replace references to final static fields of primitive 
types with primitive constants, this functionality is not required. 
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The Java Card Export file format is presented using pseudo structures written in a C-like 
structure notation. To avoid confusion with the fields of Java Card Virtual Machine classes 
and class instances, the contents of the structures describing the Java Card CAP file format 
are referred to as items. Unlike the fields of a C structure, successive items are stored in the 
Java Card file sequentially, without padding or alignment. 

Variable-sized tables, consisting of variable-sized items, are used in several class file 
structures. Although we will use C-like array syntax to refer to table items, the fact that 
tables are streams of varying-sized structures means that it is not possible to directly translate 
a table index into a byte offset into the table. 

A data structure that is referred to as an array, the elements are equal in size. 



1 Export File Name 

The name of a Export file must be the last portion of the package specification followed by 
the extension \exp\ For example, the name of the Export file of the javacard.framework 
package must be framework.exp. Operating systems that impose limitations on file name 
lengths may transform an Export file's name according to its conventions. 

CAP files are contained in a JAR file (Section 6.1.1, "Containment in a JAR File," on 
page 6-55). If an Export file is stored in a JAR file along with the CAP file, it must also be 
located in a directory called javacard that is a subdirectory package's directory. For example, 
the framework.exp file would be located in the subdirectory javacard/framework/javacard. 



2 Export File 

An Export file is defined by the following structure: 

ExportFile { 

u4 magic 

u1 minor_version 

u1 major_version 

u2 constantj300l_count 

cpjnfo constant jool[constantj30ol_count] 

u2 this_package 

u2 export_class_count 

classjnfo classes[export_class_count] 

} 

The items in the ExportFile structure are as follows: 
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magic 



The magic item contains the magic number identifying the ExportFile format; it 
has the value OxOOFACADE. 

minor_version t major_version 

The minor_version and major_version items are the minor and major version 
numbers of this Export file. An implementation of a Java Card Virtual Machine 
supports Export files having a given major version number and minor version 
numbers in the range 0 through some particular minor version. 

If a Java Card Virtual Machine encounters a Export file with the supported major 
version but an unsupported minor version, the Java Card Virtual Machine must not 
attempt to interpret the content of the Export file. However, it will be feasible to 
upgrade a the Java Card Virtual Machine to support the newer minor version. 

A Java Card Virtual Machine must not attempt to interpret a Export file with a dif- 
ferent major version. A change of the major version number indicates a major 
incompatibility change, one that requires a fundamentally different Java Card Vir- 
tual Machine. 

In this specification, the major version of the Export file has the value 2 and the* 
minor version has the value 1. Only Sun Microsystems, Inc. may define the mean- 
ing and values of new Export file versions. 

constant_pool_count 

The constant_pool_count item is a non-zero, positive value that indicates the 
number of constants in the constant pool. 

constant_poolQ 

The constant_pool is a table of variable-length structures representing various 
string constants, class names, field names and other constants referred to within 
the ExportFile structure. 

Each of the COnstant_pool table entries, including entry zero, is a variable-length 
structure whose format is indicated by its first "tag" byte. 

this_package 

The value of this_package must be a valid index into the constant_pool table. 
The constant_pool entry at that index must be a CONSTANT_Package_info 
structure representing the package defined by this ExportFile. 

export_class_count 

The value of the export_clas$_count item gives the number of publicly accessi- 



Chapter 5 The Export Fil Format 39 



ble classes defined in this package. 



classesQ 

Each value of the classes table must be a variable-length class jnfo structure 
giving the complete description of a publicly accessible class declared in this pack- 
age. 



3 Constant Pool 

All constant_pool table entries have the following general format: 

cpjnfo { 

u1 tag 
u1 infoQ 

} 

Each item in the constant_pool must begin with a 1-byte tag indicating the kind of cpjnfo 
entry. The content of the info array varies with the value of tag. The valid tags and their 
values are listed in TABLE 5-1. Each tag byte must be followed by two or more bytes giving 
information about the specific constant. The format of the additional information varies with 
the tag value. 

TABLE 5-1 Constant Pool Tags 



Constant Type 


Value 


CONSTANT_Package 


13 


CONSTANT_Interfaceref 


7 


CONSTANT_Integer 


3 


CONSTANT_Utf 8 





. 1 CONSTANT_Package 

The CONSTANT_Package_info structure is used to represent a package: 

CONSTANT_Packagejnfo { 
u1 tag 
u1 flags 
u2 namejndex 
u1 minor_version 
u1 major_version 
u1 aidjength 
u1 aid [aidjength] 

} 
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The items of the CONSTANT_PackageJnfo structure are the following: 
tag 

The tag item has the value of CONSTANT_Package (13). 

flags 

The flags item is a mask of modifiers that apply to this package. The flags modifi- 
ers are shown in the following table. 



table 5-2 Package Flags 



Flags 


Value 


ACC — LIBRARY 


0x01 



The ACCJJBRARY flag has the value of one if this package does not define and 
declare any applets. In this case it is called a library package. Otherwise 
ACCJJBRARY has the value of 0. 

If the package is not a library package this export file may only contain shareable 
interfaces. A shareable interface is either the javacard.framework.Sharable inter- 
face or extends that interface. 



Note - The restriction on exporting non-sharable items is imposed by the firewall 
defined in the Java Card Runtime Environment 2.1 specifications. 

All other flag values are reserved by the Java Card Virtual Machine. Their values 
must be zero. 

namejndex 

The value of the namejndex item must be a valid index into the constant jdooI 
table. The constantjool entry at that index must be a CONSTANTJJtf8_info 
structure representing a valid Java package name. 

As in Java class files, ASCII periods (V) that normally separate the identifiers in a 
package name are replaced by ASCII forward slashes (V). For example, the pack- 
age name javacard.framework is represented in a CONST ANTJJtf8_info struc- 
ture as javacard/framework. 

minor_version, major_version 

The minor_version and major_version items are the minor and major version 
numbers of this package. These values uniquely identify the particular implemen- 
tation of this package and indicate the binary compatibility between packages. 
They are used to determine whether references between packages can be resolved, 
given the particular implementations. 
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A change in the minor version of a package represents an extension to the API and/ 
or an update to the internal implementation that does not change the functionality 
of the API. It is guaranteed that two revisions of a package with the same major 
version and different minor versions have the same public token values assigned to 
the elements they have in common. 

A change in the major version of a package represents an incompatibility with 
revisions of a lesser major version. This indicates that a portion of the API of the 
package has been deprecated and/or the implementation of the API is not function- 
ally equivalent. Public tokens assigned to elements of the API that are defined in 
revisions of a package with different major versions are not required to have the 
same values. 

A Java Card Virtual Machine may resolve references to an executable form of the 
package described in this Export file if the version associated with that executable 
has the same major version and a minor version that is less than or equal to this 
minorversion value. 

The package provider is required to assign major and minor versions to different 
revisions of the package according to the constraints specified in this specification. 

aidjength 

The value of the aidjength item gives the number of bytes in the aid array. Valid 
values are between 5 and 16, inclusive. 

aidQ 

The aid array contains the ISO AID of the package. See ISO 7816-5 for a defini- 
tion of an AID. 

.2 CONSTANTJnterfaceref 

The CONSTANTJnterfaceref Jnfo structure is used to represent an interface: 

CONSTANTJnterfaceref Jnfo { 
u1 tag 

u2 namejndex 

} 

The items of the CONSTANTJnterfaceref Jnfo structure are the following: 
tag 

The tag item has the value of CONSTANTJnterface (7). 
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namejndex 

The value of the namejndex item must be a valid index into the constant _pool 
table. The constant_pool entry at that index must be a CONST ANT_Utf8_info 
structure representing a valid fully qualified Java interface name. These names are 
fully qualified because they may be defined in a package other than the one 
described in the Export File. 

As in Java class files, ASCII periods (V) that normally separate the identifiers in a 
class or interface name are replaced by ASCII forward slashes (V). For example, 
the interface name sun.jc.interfacel is represented in a CONSTANT_Utf8_info 
structure as sun/jc/interface1 . 



5.3.3 CONSTANTJnteger 

The CONSTANTJntegerjnfo structure is used to represent four-byte numeric (int) 
constants: 

CONSTANTJntegerjnfo { 
u1 tag 
u4 bytes 

} 

The items of the CONSTANTJntegerjnfo structure are the following: 
tag 

The tag item has the value of CONSTANTJnteger (3). 

bytes 

The bytes item of the CONSTANTJntegerjnfo structure contains the value of 
the int constant. The bytes of the value are stored in big-endian (high byte first) 
order. 



5.3.4 CONSTANT Utf8 

The CONSTANTJJtf8Jnfo structure is used to represent constant string values. UTF-8 
strings are encoded in the same way as described in The Java Virtual Machine Specification, 
Section 4.4.7. 

The CONSTANT Utf8 info structure is: 
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CONSTANT_Utf8_info { 
u1 tag 
u2 length 
u1 bytes[length] 

} 

The items of the CONSTANTJJtf8_info structure are the following: 
tag 

The tag item has the value of CONSTANTJJtf8 (1). 

length 

The value of the length item gives the number of bytes in the bytes array (not the 
length of the resulting string). The strings in the CONSTANTJJtf8_info structure 
are not null-terminated. 

bytesQ 

The bytes array contains the bytes of the string. No byte may have the value 
(byte)O or (byte)0xF0-(byte)0xFF. 



4 Classes 

Each interface and class is described by a variable-length class_info structure. The format of 
this structure is: 

classjnfo { 

u1 token 

u2 access_flags 

u2 namejndex 

u2 export_interfaces_count 

u2 interfaces[exportjnterfaces_count] 

u2 export_fields_count 

fieldjnfo fields[export_fields_count] 

u2 export_methods_count 

methodjnfo methods[export_methods_count] 

} 

The items of the classjnfo structure are as follows: 
token 

The value of the token item is used to reference this class or interface on a Java 
Card. The tokens for all the public classes in a package are numbered consecu- 
tively starting at zero; beyond that the ordering of class tokens is not specified. 
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access_flags 

The value of the accessjiags item is a mask of modifiers used with class and 
interface declarations. The access_flags modifiers are shown in the following 
table. 



TABLE 5-3 Class access and modifier flags 



Name 


Value 


Meaning 


Used By 


ACC_PUBLIC 


0x0001 


Is public; may be 
accessed from outside 
its package 


Class, interface 


ACC_FINAL 


0x0010 


Is final; no subclasses 
allowed. 


Class 


ACC_INTERFACE 


0x0200 


Is an interface 


Interface 


ACC_ABS TRACT - 


0x0400 


Is abstract; may not be 
instantiated 


Class, interface 


ACC_S HARE ABLE 


0x0800 


Is shareable, may be 
shared between Java 
Card applets. 


Class, interface 



The ACC_SHAREABLE flag indicates whether this class or interface is share- 
able. A class is shareable if it implements (directly or indirectly) the javac- 
ard.framework.shareable interface. An interface is shareable if it is or implements 
(directly or indirectly) the j avacard.fr ameworkShareable interface. 



Note - The ACC_SHAREABLE flag is defined to enable Java Card Virtual 
Machines to implement the firewall restrictions defined by the Java Card Runtime 
Environment 2. 1 specifications. 

All other class access and modifier flags are defined in the same way and with the 
same restrictions as described in The Java Virtual Machine Specification, Section 
4.1. 

The Java Card Virtual Machine reserves all other flag values. Their values must be 
zero. 

namejndex 

The value of the namejndex item must be a valid index into the constant_pool 
table. The constantjDOOl entry at that index must be a CONSTANT_Utf8 jnfo 
structure representing a valid Java class name stored as a simple (not fully quali- 
fied) name, that is, as a Java identifier. 1 

1. In Java class files class names are fully qualified. In Java Card Export files all classes 
enumerated are defined in the package of the Export file making it unnecessary for class 
names to be fully qualified. 
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export_interfaces_count 

The value of the export jnterface_count item indicates the number of externally 
accessible interfaces implemented by this class or interface. It does not include 
package visible interfaces. It does include all superinterfaces in the hierarchy of 
public interfaces implemented by this class or interface. 

interfacesQ 

Each value in the interfaces array must be a valid index into the constant _pool 
table. The constantjpool entry at each value of interfaces[i], where 0 <= i < 
exportjnterfaces_count, must be a CONSTANTJnterfacerefjnfo structure 
representing an interface which is an externally accessible superinterface of this 
class or interface type, in the left-to-right order given in the source for the type and 
its superclasses or superinterfaces. 

export_fields_count 

The value of the export_fields_COunt item gives the number of externally acces- 
sible fields declared by this class. 

fieldsQ 

Each value in the fields table must be a variable-length fieldjnfo structure giving 
a description complete enough to link to the field in a Java Card. The fieldjnfo 
structures represent all publicly accessible fields, both class variables and instance 
variables, declared by this class. It does not include items representing fields that 
are inherited from superclasses. 

export_methods_count 

The value of the export_methods_count item gives the number of externally acces- 
sible methods declared by this class. 

methodsQ 

Each value in the methods table must be a method jnfo structure giving a 
description complete enough to link to the method in a Java Card. The 
method jnfo structures represent all publicly accessible class (static) methods 
implemented by this class, and all publicly accessible instance methods imple- 
mented by this class or its superclasses, or defined by this interface or its super- 
interfaces. 
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Fields 



Each field is described by a variable-length fieldjnfo structure. The format of this structure 
is: 

fieldjnfo { 

u1 token 
u2 access_flags 
u2 namejndex 
u2 descriptorjndex 
u2 attributes_count 

attribute_infoattributes[attributes_count] 

} 

The items of the fieldjnfo structure are as follows: 
token 

The value of the token item is used to reference this field on a Java Card. There 
are three scopes for token values of fields: final static fields of primitives, other 
static fields, and instance fields. 

The value of the token item for all final static fields of primitive types {boolean, 
byte, short, and int) is OxFFFF. Final static fields of primitive types are represented 
in the ExportFile structure, but are not assigned token values suitable for on-card 
referencing. These fields are not represented in a CAP file or on Java Cards. 
Instead converters must replace bytecodes that reference final static fields of prim- 
itive types with bytecodes that load the constant value of the field. 

The value of the token item for all other static fields in a class are numbered con- 
secutively starting at zero, except that the token after an int field is skipped and the 
token for the following field is numbered two greater than the token of the int field. 
Beyond that the ordering of static field token assignment is not specified. 

The value of the token item for all the instance fields in a class are numbered con- 
secutively starting at zero, except that the token after an int field is skipped and the 
token for the following field is numbered two greater than the token of the int field. 
The tokens for non-reference fields must be numbered less than the tokens for ref- 
erence fields; beyond that the ordering of instance fields is not specified. 

access_flags 

The value of the access_flags item is a mask of modifiers used with class and 
interface declarations. The access_flag$ modifiers are shown in the following 
table. 
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TABLE 5-4 Field access and modifier flags 



Name 


Value 


Meaning 


Used By 


ACC_PUBLIC 


0x0001 


Is public; may be 
accessed from outside its 
package. 


Any field 


ACC_PROTECTED 


0x0004 


Is protected; may be 
accessed within 
subclasses. 


Class field 


ACC_STATIC 


0x0008 


Is static. 


Class field 


ACC_FINAL 


0x0010 


Is final; no further 
overriding or assignment 
after initialization. 


Any field 



Field access and modifier flags are defined in the same way and with the same 
restrictions as described in The Java Virtual Machine Specification, Section 4.5. 



name_index 

The value of the name_index item must be a valid index into the constant _pool 
table. The constant_pool entry at that index must be a CONSTANT_Utf8 jnfo 
structure representing a valid Java field name stored as a simple (not fully quali- 
fied) name, that is, as a Java identifier. 

descriptorjndex 

The value of the descriptorjndex item must be a valid index into the 
constant jdooI table. The constant_pool entry at that index must be a 
CONSTANTJJtf8_info structure representing a valid Java field descriptor. 

Representation of a field descriptor in an Export File is the same as in a Java Class 
file. See the specification described in The Java Virtual Machine Specification, 
Section 4.3.2. 

attributes_count 

The value of the attributes_count item indicates the number of additional 
attributes of this field. For static final fields the value must be 1; that is, when both 
the ACC_STATIC and ACC_FINAL bits in the flags item are set an attribute 
must be present. For all other fields the value must be 0. 

attributesQ 

The only attribute defined for the attributes table of a fieldjnfo structure by this 
specification is the ConstantValue attribute. This must be defined for static final 
fields of primitives (boolean, byte, short, and int). 
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Methods 



Each method is described by a van able- length methodjnfo structure. The format of this 
structure is: 

method jnfo { 

u1 token 
u2 access_flags 
u2 namejndex 
u2 descriptorjndex 

} 

The items of the methodjnfo structure are as follows: 
token 

The value of the token item is used to reference this method on a Java Card. There 
are two scopes for token values of methods: static methods, and instance methods. 

The static method scope includes constructors. The tokens for all the static meth- 
ods and constructors in a class are numbered consecutively starting at zero. 
Beyond that ordering is not specified. 

The tokens for introduced instance methods in a class are numbered consecutively 
starting at one greater than the highest numbered instance method token of the 
class's superclass. If a method overrides a method implemented in the class's 
superclass, that method uses the same token number as the method in the super- 
class. Beyond that the ordering of instance methods is not specified. 

The maximum token value for an instance method is 127. 

access_flags 

The value of the access_f!ags item is a mask of modifiers used with class and 
interface declarations. The access_flags modifiers are shown in the following 
table. 
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TABLE 5-5 Method access and modifier flags 



Name 


Value 


Meaning 


Used By 


ACC_PUBLIC 


0x0001 


Is public; may be accessed 
from outside its package. 


Any method 


ACC_PROTECTED 


0x0004 


Is protected; may be 
accessed within subclasses. 


Class/instance 
method 


ACC_STATIC 


0x0008 


Is static. 


Class/instance 
method 


ACC_FINAL 


0x0010 


Is final; no further 
overriding or assignment 
after initialization. 


Class/instance 
method 


AC C_ABS TRACT 


0x0400 


Is abstract; no 
implementation is provided 


Any method 



Method access and modifier flags are defined in the same way and with the same 
restrictions as described in The Java Virtual Machine Specification, Section 4.6. 

Unlike in Java class files, the ACC_NATIVE flag is not supported in Export files. 
Whether a method is native is an implementation detail that is not relevant to refer- 
encing packages. 

namejndex 

The value of the namejndex item must be a valid index into the constant jdooI 
table. The constantjaool entry at that index must be a CONSTANT_Utf8jnfo 
structure representing either the special internal method name for constructors, 
<init>, or a valid Java method name stored as a simple (not fully qualified) name. 

descriptorjndex 

The value of the descriptorjndex item must be a valid index into the 
constant jdooI table. The constantjjool entry at that index must be a 
CONSTANT_Utf8 jnfo structure representing a valid Java method descriptor. 

Representation of a method descriptor in an Export File is the same as in a Java 
Class file. See the specification described in The Java Virtual Machine Specifica- 
tion, Section 4.3.3. 



7 Attributes 

Attributes are used in the field jnfo structure of the Export File format. All attributes have 
the following general format: 
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attributejnfo { 

u2 attribute_name_index 
u4 attributejength 
u1 info[attributeJength] 

} 



5.7.1 ConstantValue Attribute 

The ConstantValue attribute is a fixed-length attribute used in the attributes table of the 
field_info structures. A ConstantValue attribute represents the value of a constant field that 
must be final static; that is, both the ACC_STATIC and ACC_FINAL bits in the flags item 
of the field jnfo structure must be set. There can be no more than one ConstantValue 
attribute in the attributes table of a given field jnfo structure. The constant field represented 
by the fieldjnfo structure is assigned the value referenced by its ConstantValue attribute as 
part of its initialization. 

The ConstantValue attribute has the format 

ConstantValue_attribute { 

u2 attributejriamejndex 
u4 attributejength 
u2 constantvaluejndex 

} 

The items of the ConstantValue_attribute structure are as follows: 

attribute_name_index 

The value of the attribute jiamejndex item must be a valid index into the 
constant jjool table. The constant_pool entry at that index must be a 
CONSTANT_Utf8jnfo structure representing the string "ConstantValue". 

attributejength 

The value of the attributejength item of a ConstantValue_attribute structure 
must be 2. 

constantvaluejndex 

The value of the constantvaluejndex item must be a valid index into the 
constant_pool table. The constant_pool entry at that index must give the con- 
stant value represented by this attribute. 

The constant_pool entry must be of a type CONSTANTJnteger. 
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The Cap File Format 



This chapter describes the Java Card Virtual Machine CAP (Converted Applet) file format. 
Each CAP file contains all of the classes and interfaces defined in one Java package. 
Compliant Java Card Virtual Machines must be capable of producing and consuming all 
CAP files that conform to the specification provided in this book. 

A CAP file consists of a stream of 8-bit bytes. All 16-bit and 32-bit quantities are 
constructed by reading in two and four consecutive 8-bit bytes, respectively. Multibyte data 
items are always stored in big-endian order, where the high -order bytes come first. 

This chapter defines its own set of data types representing Java Card CAP file data: The 
types ul, and u2 represent an unsigned one-, and two-byte quantities, respectively. Some ul 
types are represented as bitfield structures, consisting of arrays of bits. The zeroeth bit in 
each bit array represents the most significant bit. 

The Java Card CAP file format is presented using pseudo structures written in a C-like 
structure notation. To avoid confusion with the fields of Java Card Virtual Machine classes 
and class instances, the contents of the structures describing the Java Card CAP file format 
are referred to as items. Unlike the fields of a C structure, successive items are stored in the 
Java Card file sequentially, without padding or alignment. 

Variable-sized tables, consisting of variable-sized items, are used in several class file 
structures. Although we will use C-like array syntax to refer to table items, the fact that 
tables are streams of varying-sized structures means that it is not possible to directly translate 
a table index into a byte offset into the table. 

A data structure that is referred to as an array, the elements are equal in size. 



Note - Many elements in this CAP file specifications are assigned token values. The 
definitions of these tokens are given in Chapter 4, "Java Card Naming." 
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1 Component Model 



A CAP file is represented as a set of components. A CAP file is not complete unless all of 
the components specified in this chapter are present, except the Applet and Export 
Components. The Applet Component ("Applet Component" on page 61) is required if the 
package defines one or more Java Card applets. The Export Component ("Export 
Component" on page 85) is required if the package is to be made available to other packages 
on a Java Card. All components have the following general format: 

component { 
u1 tag 
u2 size 
u1 infoQ 

} 

Each component begins with a 1-byte tag indicating the kind of component. Valid tags and 
their values are listed in the next table. The size item indicates the number of bytes in the 
info array of the component, not including the tag and size items. The content and format of 
the info array varies with the type of component. 



TABLE 6-1 Component Tags 



Component Type 


Value 


COMPONENT_Header 


1 


COMPONENT_Directory 


2 


COMPONENT_Applet 


3 


COM PONENT_Impo r t s 


4 


COMPONENT__ConstantPool 


5 


COMPONENT_Class 


6 


COMPONENT _Method 


7 


COMPONENTjStaticField 


8 


COMPONENT ReferenceLocation 


9 


COMPONENT_Export 


10 


COMPONENT_Descriptor 


11 



Sun may define additional components in future versions of the CAP file specification. 
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6.1.1 



Containment in a JAR File 



All CAP file components are represented in individual files stored in a JAR File. The JAR 
path/file names are enumerated in the following table. The names of each of the component 
files are not case sensitive. Operating systems that impose limitations on file name lengths 
may transform an component file names according to its conventions. 



TABLE 6-2 JAR File Names 



Component Type 


File Name 


COMPONENT_Header 


Header .cap 


COMPONENT_Di rectory 


Directory . cap 


COMPONENT_Applet 


Applet .cap 


COMPONENT_Imports 


Imports . cap 


COMPONENT_ConstantPool 


ConstantPool . cap 


COMPONENT_Class 


Class . cap 


COMPONENT_Me t hod 


Method. cap 


COMPONENT_StaticField 


StaticField. cap 


COMPONENT_ReferenceLocation 


Ref Locations . cap 


COMPONENT_Export 


Export. cap 


COMPONENT_Descriptor 


Descriptor . cap 



The location within a JAR file of the files that constitute a CAP file is in a directory called- 
javacard that is a subdirectory representing the package's directory. For example, the CAP 
file component files for the package javacard. framework are located in the subdirectory 
javacard/ framework/ javacard. 

The name of a JAR file containing a CAP file is not defined as part of this specification. ' 
Other files, including other CAP files, may also reside in the JAR file. 



6.1.2 Defining New Components 

Java Card CAP files are permitted to contain new components. All components not defined 
as part of this Java Card Virtual Machine specification must not affect the semantics of the 
content of the specified components, and Java Card Virtual Machines must be able to accept 
CAP files that do not contain new components. Java Card Virtual Machine implementations 
are required to ignore components they do.not recognize. 
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New components are named in two ways. They are assigned both an ISO 7816-5 AID and a 
tag. Valid tag values are between 128 and 255, inclusive. The Directory Component 
("Directory Component" on page 59) must contain an entry in the custom_component item 
specifying both the AID and associated tag. The new component must contain the tag value 
as its first item. 

The JAR path/file names of custom components must follow the same restrictions as those 
specified in Section 6.1.1, "Containment in a JAR File." That is, they must be located in the 
<package_directory>/yavacarJ subdirectory of the JAR file and must have the extension 
\cap\ 



2 Header Component 

The Header Component is described by the following variable-length structure: 
header_component { 
u1 tag 
u2 size 
u4 magic 
u1 minor_version 
u1 major_version 
u1 flags 

packagejnfo this_package 

} 

The items in the header_component structure are as follows: 
tag 

The tag item has the value COMPONENTJHeader(l). 

size 

The size item indicates the number of bytes in the header_component structure, 
excluding the tag and size items. 

magic 

The magic item supplies the magic number identifying the Java Card CAP file 
format; it has the value OxDECAFFED. 

minor_version, major_version 

The minor_version and major_version items are the minor and major version 
numbers of this CAP file. An implementation of a Java Card Virtual Machine 
must support CAP files having a specific major version number and minor version 
numbers in the range of 0 through some particular rninor version. 
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If a Java Card Virtual Machine encounters a CAP file with the supported major 
version but an unsupported minor version, the Java Card Virtual Machine must not 
attempt to interpret the content of the CAP file. However, it will be feasible to 
upgrade a the Java Card Virtual Machine to support the newer minor version. 

A Java Card Virtual Machine must not attempt to interpret a CAP file with a dif- 
ferent major version. A change of the major version number indicates a major 
incompatibility change, one that requires a fundamentally different Java Card Vir- 
tual Machine. 

In this specification, the major version of the CAP file has the value 2 and the 
minor version has the value 1. Only Sun Microsystems, Inc. may define the mean- 
ing and values of new CAP file versions. 

flags 

The flags item is a mask of modifiers that apply to this package. The flags modifi- 
ers are shown in the following table. 



table 6-3 Package Flags 



Flags 


Value 


ACC_INT 
ACC_EXPORT 


0x01 
0x02 


ACC_APPLET ' 


0x04 



The ACCJNT flag has the value of one if the Java int type is present in this pack- 
age. This includes fields defined as type int, fields defined as type int array, or 
instructions of type int. Otherwise the ACC_INT flag has the value of 0. 

The ACC_EXPORT flag has the value of one if other packages may link to this 
package. Otherwise it has the value of 0. If the ACC_EXPORT flag has the value 
of one an Export Component ("Export Component" on page 85) must be defined 
in this CAP file. If the ACC_EXPORT flag has the value of zero an Export Com- 
ponent must not be defined in the CAP file. 

The ACC_APPLET flag has the value of one if one or more Java Card applets are 
defined this package. Otherwise it has the value of 0. If the ACC_APPLET flag 
has the value of one an Applet Component ("Applet Component" on page 61) 
must be defined in this CAP file. If the ACC_APPLET flag has the value of zero 
an Applet Component must not be defined in the CAP file. 

The Java Card Virtual Machine reserves all other flag values. Their values must 
be zero. 
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this_package 

The this _package item describes the package defined in this CAP file. It is rep- 
resented as a package_info structure: 

packagejnfo { 

u1 minor_version 
u1 major_version 
u1 AIDJength 
u1 AID[AIDJength] 

} 

minor_version, major_version 

The minor_version and major_version items are the minor and major 
version numbers of this package. These values uniquely identify the par- 
ticular implementation of this package and indicate the binary compatibil- 
ity between packages. These versions are used when resolving references 
between packages in preparation for execution. 

A change in the minor version of a package represents an extension to the 
API and/or an update to the internal implementation that does not change 
the functionality of the API. It is guarenteed that two revisions of a pack- 
age with the same major version and differenct minor versions have the 
same public token values assigned to the elements they have in common. 

A change in the major version of a package represents an incompatibility 
with revisions of a lesser major version. This indicates that a portion of 
the API of the package has been deprecated and/or the implementation of 
the API is not functionally equivalent. Public tokens assigned to elements 
of the API that are defined in revisions of a package with different major 
versions are not required to have the same values. 

A Java Card Virtual Machine may link another package to this package if 
and only if the other package's CAP file has been constructed using a 
revision of this package that has the same major version and a minor ver- 
sion less than or equal to the minor version specified by the 
major_version and minor_version items. The Imports Component 
Section 6.5, "Imports Component," on page 6-62 in the CAP file of the 
referencing package contains both the Java Card name (AID) of the refer- 
enced package and its major and rninor versions. 

The package provider is required to assign major and minor versions to 
different revisions of the package according to the constraints specified in 
this specification. 

AIDJength 
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The AIDJength item represents the length of the AID item. Valid values 
are between 5 and 16, inclusive. 

AIDD 

The AID item represents the Java Card name of the package. See ISO 
7816-5 for the definition of an ADD. 



Directory Component 

The Directory Component lists the size of each of the components defined in this CAP file. 
It is described by the following variable-length structure: j 

directory_component { 
u1 tag 
u2 size 

u1 basic_count 
u1 custom_count 
{ u1 component_tag 
u2 size 

} basic_components[basic_count] 
{ u1 componenMag 

u2 size 

u1 AIDJength 

u1 AID[AIDJength] 
} custom_components[custom_count] 

} 

The items in the directory_component structure are as follows: 
tag 

The tag item has the value COMPONENT_Directory(2). 

size 

The size item indicates the number of bytes in the directory_component struc- 
ture, excluding the tag and size items. 

basic_count 

The basic_count item indicates the number of basic components defined in this 
CAP file. These components are defined in this specification. Valid values for the 
basic_count item are 9, 10 and 1 1, depending upon whether an Export Compo- 
nent and/or Applet Component are defined. 
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custom_count 

The custom_count item indicates the number of components defined in this CAP 
file that are not defined in this specification. Valid values are between 0 and 127, 
inclusive. 

basic_componentsQ 

The basic_COmponents item represents an array of structures, each representing 
a component defined in this CAP file. The items in the structure are: 

component_tag 

The component_tag item represents the tag of the component. Valid 
values are defined in Table 6-1, "Component Tags," on page 54. 

size 

Except in the case of the Static Field Component, the size item represents 
the size in bytes in the component, including the tag and size items. 

For the Static Field Component the size item represents the size in bytes 
of the Static Field Image. This value is equal to the byte_count item in the 
static field_component structure. It does not include the number of bytes 
required to store the array instances defined in the Static Field Compo- 
nent. 

custom_componentsQ 

The custom_components item represents an array of variable-length structures 
that name each of the components in this CAP file that are not defined by this stan- 
dard. Each component is assigned an AID conforming to the ISO 7816-5 standard. 
The RID (first 5 bytes) of all of the custom component's AID must have the same 
value. In addition, the RID of the custom component's AID must have the same 
value as the RID of the package defined in this CAP file. 

The items in entries of the custom_component table are: 
component_tag 

The componenMag item represents the tag of the component. Valid 
values are between 128 and 255, inclusive. 

size 

The size item represents the size in bytes of the component. 
AIDJength 

The AIDJength item represents the length of the AID item. Valid values 
are between 5 and 16, inclusive. 
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AIDQ 

The AID item represents the Java Card name of the component. See ISO 
7816-5 for the definition of an ADD. 



Applet Component 

The Applet Component describes each of the applets defined in this package. It is described 
by the following variable-length structure 
applet_component { 
u1 tag 
u2 size 
u1 count 
{ u1 AIDJength 
u1 AID[AIDJength] 
u2 installjnethod_offset 
} applets[count] 

} 

The items in the appIet_COmponent structure are as follows: 
tag 

The tag item has the value COMPONENT_Applet(3). 

size 

The size item indicates the number of bytes in the applet_component structure, 
excluding the tag and size items. 

count 

The count item indicates the number of applets defined in this package. 
appletsQ 

The applets item represents an array of structures that describe each of the applets 
defined in this package. Each applet is assigned an AID conforming to the ISO 
7816-5 standard. The RID (first 5 bytes) of all of the applet's AID must have the 
same value. In addition, the RID of each applet's AID must have the same value as 
the RID of the package defined in this CAP file. 



The items in the applets structure are defined as follows: 



AIDJength 

The AIDJength item represents the length of the AID item. Valid values 
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are between 5 and 16, inclusive. 

AIDO 

The AID item represents the Java Card name of the applet. 

install_method_offset 

The value of the install jriethod_offset item must be a 16-bit offset into 
the info item of the Method Component. The item at that offset must be a 
methodjnfo structure that represents the static installQ method of a 
class that extends javacard.frameworkapplet. This method is called to 
initialize the applet. 

• Restrictions placed on the installf) method of an applet are imposed by theJava Card 2. J Runtime Environment 
Specification. 



6.5 Imports Component 

The Imports Component enumerates the packages that are referenced by this package. It 
does not include the package defined in this CAP file. The Imports Component is 
represented by the following structure: 
imports_component { 

u1 tag 

u2 size 

u1 count 

packagejnfo packages[count] 

} 

The items in the imports_component structure are as follows: 
tag 

The tag item has the value COMPONENT Jmports(4). 

size 

The size item indicates the number of bytes in the imports_component structure, 
excluding the tag and size items. 

count 

The count item indicates the number of items in the packages table. The value of 
the count item must be less than or equal to 127. 
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packagesQ 

The packages item represents a table of variable-length packagejnfp structures 
as defined for "this_package" on page 58. The table contains an entry for each of 
the packages referenced in the CAP file, not including the package defined. 

The major and minor versions specified in the package_info structure are equal to 
the major and minor versions specified in the referenced package's Export File. 
Java Card Virtual Machines must compare these values with the version associated 
with the executable image of the referenced package in order to determine whether 
the two are compatible. Compatibility rules are specifed in "minorversion, 
majorversion" on page 58. 

The value of a package_token assigned to an imported package must be equal to 
the index into the packages table to the entry for that package. 



Constant Pool Component 

The Constant Pool Component describes the classes, methods, and fields referenced in the * 
Method Component ("Method Component" on page 76) of this package. The component is - 
described by the following structure: 

constant_pool_component { 
u1 tag 
u2 size 
u2 count 

cpjnfo constant_pool[count] 

} 

The items in the constant_pool_component structure are as follows: 
tag 

The tag item has the value COMPONENT_ConstantPool(5). 

size 

The size item indicates the number of bytes in the constant_pool_component 
structure, excluding the tag and size items. 

count 

The count item represents the number entries in the constants array. 
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constant_pool 

The constant_pool item represents a table of cp_info structures: 

cp jnfo { 

u1 tag 
u1 info[] 

} 

Each item in the constant jool table represents a 4-byte structure. Each structure 
must begin with a 1-byte tag indicating the kind of cpjnfo entry. The content of 
the info array varies with the value of the tag. The valid tags and their values are 
listed in the following table. The format of the additional information varies with 
the tag value. 



TABLE 6-4 Constant Pool Tags 



Constant Type 


Tag 


CONSTANT_Classref 


1 


CONSTANT_InstanceFieldref 


2 


CONSTANT_VirtualMethodref 


3 


CONSTANT_Supe rMe thodre f 


4 


CONSTANT_StaticFieldref 


5 


CONSTANT_StaticMethodref 


6 



Java Card constant types are more specific than those in Java class files. The cate- 
gories are based not only on the type of the item references but also on the manner 
in which it is referenced and located in other CAP file components. For example 
virtual methods invoked using the Java super keyword are located through the vir- 
tual method tables in a classjnfo structure (Section 6.7.1, "interface info and 
class_info," on page 6-71), but unlike virtual method references can be resolved to 
direct references on a Java Card. 

There are no ordering constraints on constant pool entries. It is recommended, 
however, that CONSTANTJnstanceFieldref constants occur first. 



.1 CONSTANT_Classref 

The CONSTANT_Classref_info structure is used to represent a reference to a class or an 
interface: 

CONSTANT_Classrefjnfo { 
u1 tag 
union { 

u2 internal_ctassjref 
{ u1 package_token 
u1 class token 
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} external_class_ref 
} classjref 
u1 padding 



The items in the CONSTANT_Classref_info structure are the following: 



The tag item has the value CONSTANT_Classref(l). 
class_ref 

The class_ref item represents a reference to a class or interface. If the class or 
interface is defined in this package the structure represents an internal_class_ref 
and the high bit of the structure is zero. If the class or interface is defined in 
another package the structure represents an external_class_ref and the high bit of 
the structure is one. 

The value of the class_ref item must not be OxFFFF. This value is reserved to 
indicate a null class reference in the super_class_ref item of class_info struc- 
tures. 

internal_class_ref 

The internal_class_ref structure represents a 16-bit offset into the info 
item of the Class Component to the interfaceinfo or classjnfo structure 
of this class or interface. This value must be less than or equal to 32767, 
inclusive, making the high bit equal to zero. 

external_class_ref 

The external_class_ref structure represents a reference to a class or 
interface defined in another package. The high bit of this structure is one. 

package_token 

The package_Joken item represents an 8-bit package token 
scoped to the CAP file. The value of this token must be equal to 
the index into the set of packages listed in the Imports Compo- 
nent to the definition of the reference package. The value of the 
package_token item must be less than or equal to 127. 

The high bit of the package_token item must be one. 
class_token 

The class_token item represents the token of the class or inter- 
face in the referenced package. 
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padding 

The padding item has the value zero. It is present to make the size of a 
CONSTANT_Classref jnfo structure the same as all other constants in the 
constant_pool. 

.2 CONSTANTJnstanceFieldref, 

CONSTANT_VirtualMethodref, and 
CONSTANT_SuperMethodref 

References to instance fields, and virtual methods are represented by similar structures: 

CONSTANT_lnstanceFieldref_info { 
u1 tag 

classjref class 

u1 instance_field_token 

} 

CONSTANT_VirtualMethodref_info { 
u1 tag 

class_ref class 

u1 virtual_methodJoken 

} 

CONSTANT_SuperMethodref_info { 
u1 tag 

class_ref class 

u1 virtual_method_token 

} 

The items in these structures are as follows: 
tag 

The tag item of a CONSTANT JnstanceFieldrefJnfo structure has the value 
CONSTANT JmtanceFieldref(2). 

The tag item of a CONSTANT_VirtualMethodref_info structure has the value 
CONSTANT_VirtualMethodref(3). 

The tag item of a CONSTANT SuperMethodref info structure has the value 
CONSTANT_SuperMethodref(4). 
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class 

The class item represents a class_ref structure (Section 6.6.1, 
"CONSTANT_Classref on page 6-64). If the referenced class is defined in 
another package the high bit of this structure has the value one. If the referenced 
class is defined in this package the high bit of this structure has the value of zero. 

The class referenced in the CONSTANT_lnstanceField_info structure must rep- 
resent the class that contains a declaration of the field. 

The class referenced in the CONSTANT_VirtualMethodrefJnfo structure must 
represent a class that contains a declaration or definition of the method. 

The class referenced in the CONSTANT_SuperMethodref Jnfo structure must 
represent the class that contains the super invocation. 

token 

The token item in the CONSTANTJnstanceFieldrefjnfo structure represents 
an instance field token, within the scope the referenced class. 

The token item of the CONSTANT_VirtualMethodrefJnfo structure represents 
a virtual method token within the scope of the referenced class. If the token item 
represents a public or protected virtual method the high bit is zero. If the token 
item represents a package-visible virtual method the high bit is one. In this case 
the class item must represent a reference to a class defined in this package. 

The token item of the CONSTANT_SuperMethodrefjnfo structure represents 
a virtual method token. Unlike in the CONSTANT_VirtualMethodref_info struc- 
ture, this item represents the token of the virtual method in the scope of the super- 
class of the class indicated by the class item. If the token item represents a public 
or protected virtual method the high bit is zero. If the token item represents a 
package-visible virtual method the high bit is one. In this case the class item must 
represent a reference to a class defined in this package and the immediate super- 
class of the class item must also be defined in this package. 



Chapter 6 The Cap File Format 67 



.3 CONSTANT_StaticFieldref and 
CONSTANT_StaticMethodref 

References to static fields and methods are represented by similar structures: 



CONSTANT_StaticFieldref jnfo { 
u1 tag 
union { 

{ u1 padding 

u2 offset 
} internal_ref 
{ u1 package Joken 

u1 class Joken 

u1 token 
} external jef 
} static Jield_ref 

} 

CONSTANT_StaticMethodref_info { 
u1 tag 
union { 

{ u1 padding 

u2 offset 
} internaljref 
{ u1 packagejoken 

u1 classjoken 

u1 token 
} externaljref 
} staticjnethod jef 

} 



The items in these structures are as follows: 
tag 

The tag item of a CONSTANT_StaticFieldref_info structure has the value 
CONSTANT_StaticFieldref{6). 

The tag item of a CONSTANT_StaticMemodref_info structure has the value 
CONSTANT_StaticMethodref(7). 

static_field_ref and static_method_ref 

The static Jield_ref and static_method_ref item represents a reference to a static 
field or static method, respectively. Static method references include references to 
static methods, constructors, and private instance methods. 

If the referenced item is defined in this package the structure represents an 
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internal_ref and the high bit of the structure is zero. If the referenced item is 
defined in another package the structure represents an external_ref and the high 
bit of the structure is one. 

internal_ref 

The interna1_ref item represents a reference to a static or method defined 
in this package. The items in the structure are: 

padding 

The padding item is equal to 0. 

offset 

The offset item of a CONSTANT_StaticFie!drefjnfo struc- 
ture represents a 16-bit offset into the Static Field Image to this 
static field. 

The offset item of a CONSTANT_StaticMethodref_info 
structure represents a 16-bit offset into the info item of the 
Method Component to a method_info structure. The 
method_info structure must represent the referenced method. 

external_ref 

The external_ref item represents a reference to a static field or method 
defined in another package. The items in the structure are: 

package_token 

The package_token item represents an 8-bit package token 
scoped to the CAP file. The value of this token must be equal to 
the index into the set of packages listed in the Imports Compo- 
nent to the definition of the referenced package. The value of 
the package_token item must be less than or equal to 127. 

The high bit of the package Joken item must be one. 
classjoken 

The class_token item represents the token of the class in the 
referenced package. 

token 

The token item of a CONSTANT_StaticFieldref_info struc- 
ture represents a static field token. It is the token of the static 
field in the referenced package. 

The token item of a CONSTANT_StaticMethodrefjnfo 
structure represents a static method token. It is the token of the 
static method in the referenced package. 
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7 Class Component 



The Class Component describes each of the classes and interfaces defined in this package. 
The information included for each interface is sufficent to uniquely identify the interface and 
to test whether or not a cast is valid. 

The information included for each class is sufficient to resolve operations associated with 
instances of a class. The operations include creating an instance, testing whether or not a 
cast is valid, dispatching virtual method invocations, and dispatching interface method 
invocations. Also included is sufficient information to locate instance fields of type 
reference. 

The Class Component is represented by the following structure: 

class_component { 
u1 tag 
u2 size 

interfacejnfo interfacesO 
class_info classesQ 

} 

The items in the class_component structure are as follows: 
tag 

The tag item has the value COMPONENT_Class(6). 

size 

The size item indicates the number of bytes in the class_component structure, 
excluding the tag and size items. 

interfaces^ 

The interfaces item represents an array of variable-length interfacejnfo struc- 
tures. Each interface defined in this packages is represented in the array. The 
entries are ordered based on hierarchy such that a superinterface has a lower index 
than any of its subinterfaces. 

classesQ 

The classes item represents an array of variable-length class_info structures. 
Each class defined in this package is represented in the array. The entries are 
ordered based on hierarchy such that a superclass has a lower index than any of its 
subclasses. 
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6.7.1 interface_info and class_info 

The interfacejnfo and class_info structures represent interfaces and classes, respectively. 
The interfacejnfo structure is a strict subset of the c!ass_info structure. The two are 
differentiated by the value of the first bit in the structure. The structures are defined as 
follows: 

interfacejnfo { 

u1 bitfield { 
bit[4] flags 
bit[4] reserved 



classjnfo { 

u1 bitfield { 
bit[4] flags 

bit[4] interface_count 

class_ref super_classjref 
u1 declared_instance_size 
u1 first j-eferencejndex 
u1 reference_count 
u1 publicjriethod_table_base 
u1 public_method_table_count 
u1 package_method_table_base 
u1 package_method_table_count 

u2 public_virtuaLmethod_table[public_method_table_count] 

u2 package_virtual_method_table[package_method_table_count] 

implemented jnterfacejnfo interfaces[interface_count] 

} 



The items of the interfacejnfo and classjnfo structure are as follows: 
flagsQ 

The flags item is a mask of modifiers used to describe this interface or class. 
Valid values are shown in the following table: 



table e-5 Interface and Class Info Flags 



Name 


Value 


ACC_ INTERFACE 
AC C_ SHARE ABLE 


0x8 
0x4 



The ACCJNTERFACE flag indicates whether this interfacejnfo or classjnfo 
structure represents an interface or a class. The value must be 1 if it represents an 
interfacejnfo structure and 0 if a classjnfo structure. 

The ACC_SHAREABLE flag in an interface_info structure indicates whether this 
interface is shareable. The value of this flag must be one if and only if the interface 
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is javacard.frameworkShareable interface or implements that interface directly or 
indirectly. 

The ACC_SHAREABLE flag in an class_info structure indicates whether this 
class is shareable. The value of this flag must be one if and only if this class or any 
of its superclasses implements an interface that is shareable. 



Note - A Java Card Virtual Machine uses the ACC_SHAREABLE flag to 
implement the firewall restrictions defined by the Java Card Runtime Environment 
2.1 specifications. 

The Java Card Virtual Machine reserves all other flag values. Their values must 
be zero. 

reserved 

The reserved item of the interface_info structure has the value of zero. 
interface_count[] 

The interface_count item of the class_info structure indicates the number of 
entries in the interfaces table item. 

super_class_ref 

The super__class_ref item of the class_info structure is a class_ref structure rep- 
resenting the superclass of this class. The class_ref structure is defined as part of 
the CONSTANT_ClassrefJnfo structure (Section 6.6.1, 
"CONSTANTClassref," on page 6-64). 

If this class does not have a superclass, the value of the super_class_ref item must 
be OxFFFF. 

declared _instance_size 

The declared_instance_size item of the class_info structure represents the num- 
ber of 16-bit cells required to represent the instance fields declared by this class. It 
does not include instance fields declared by superclasses of this class. 

Instance fields of type int are represented in two 16-bit cells, while all other field 
types are represented in one 16-bit cell. 

first_reference_token 

The first_reference_token item of the class_info structure represents the token 
value of the first reference-type instance field defined by this class. It does not 
include instance fields defined by superclasses of this class. 
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reference_count 

The reference_count item of the class_info structure represents the number of 
reference-type instance field defined by this class. It does not include reference- 
type instance fields defined by superclasses of this class. 

public_method_table_base 

The public_method_table_base item of the class_info structure must be equal 
to the token value of the first method in the public_virtual_method_table array. 

public_method_table_count 

The public_method_table_count item of the classjnfo structure indicates the 
number of entries in the public j/irtualjriethodjable array. 

If this class does not define any public or protected override methods, the mini- 
mum valid value of publicjriethod_table_count item is the number of public 
and protected virtual methods declared by this class. If this class defines one or 
more public or protected override methods, the minimum valid value of 
public_method_table_count item is the value of the largest public or protected 
virtual method token, minus the value of the smallest public or protected virtual 
method token, plus one. 

The maximum valid value of the public jTiethod_table_count item is the value 
of the largest public or protected virtual method token, plus one. 

Any value for the public_method_table_count item between the minimum and 
maximum specified here are valid. However, the value must correspond to the 
number of entries in the public j/irtualjriethodjable. 

package_method_table_base 

The package jnethodJable_base item of the classjnfo structure must be equal 
to the token value of the first entry in the package j/irtualjnethodjable array. 

packagejnethodJable_count 

The package_jnethod_table_count item of the classjnfo structure indicates the 
number of entries in the package j/irtualjnethodjable array. 

If this class does not define any override methods, the minimum valid value of 
package jnethod_table_count item is the number of package visible virtual 
methods declared by this class. If this class defines one or more package visible 
override methods, the minimum valid value of packagejnethod_table_count 
item is the value of the largest package visible virtual method token, minus the 
value of the smallest package visible virtual method token, plus one. 

The maximum valid value of the package_method_table_count item is the 
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value of the largest package visible method token, plus one. 

Any value for the package_method_table_count item between the minimum 
and maximum specified here are valid. However, the value must correspond to the 
number of entries in the package_virtual_method Jable. 

public_virtual_method_table 

The public_virtual_method_table item of the classjnfo structure represents an 
array of public and protected virtual methods that can be invoked on an instance of 
this class. It includes methods declared or defined by this class. It may also include 
methods declared or defined by any or all of its superclasses. The value of an index 
into this table must be equal to the value of the virtual method token of the indi- 
cated method minus the value of the public_method_table_base item. 

Entries in the public_virtual_method_table array that represent methods defined 
or declared in this package contain offsets into the info item of the Method Com- 
ponent (Section 6.8, "Method Component," on page 6-76) to the methodjnfo 
structure representing the method. Entries that represent methods defined or 
declared in another package contain the value OxFFFF. 

Entries for methods that are declared abstract, not including those defined by inter- 
faces, are represented in the public_virtual_method_table array in the same way 
as non-abstract methods. 

package_virtual_method_table 

The package_virtualjnnethod_table item of the classjnfo structure represents 
an array of package virtual methods that can be invoked on an instance of this 
class. It includes methods declared or defined by this class. It may also include 
methods declared or defined by any or all of its superclasses that are defined in this 
package. The value of an index into this table must be equal to the value of the vir- 
tual method token of the indicated method & 0x7F, minus the value of the 
package_method_table_base item. 

All entries in the package_virtual_method Jable array represent methods 
defined or declared in this package. They contain offsets into the info item of the 
Method Component ("Method Component" on page 76) to the methodjnfo 
structure representing the method. 

Entries for methods that are declared abstract, not including those defined by inter- 
faces, are represented in the package_virtual_method_table array in the same 
way as non-abstract methods. 

interfaces!] 

The interfaces item of the class_info structure represents a table of 
implemented jnterface jnfo structures. The table must contain an entry for each 
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of the interfaces indicated in the declaration of this class and each of the interfaces 
in the hierarchies of those interfaces. Interfaces that occur more than once are rep- 
resented by a single entry. Interfaces implemented by superclasses of this class 
may optionally be represented. 

Given the declarations below, the number of entries for class cO is 1 and the entry 
in the interfaces array is iO. The minimum number of entries for class cl is 3 and 
the entries in the interfaces array are il, i2, and i3. The entries class cl may also 
include interface iO, which is implemented by the superclass of cl. 



interface iO {} 

interface il { } 

interface i2 extends il { } 

interface i3 { } 

class cO implements iO { } 

class cl extends cO implements i2, i3 

{} 



The implemented jnterfacejnfo structure is defined as follows: 

implemented jnterfacejnfo { 
class_ref interface 
u1 count 
u1 index[count] 

} 

interface 

The interface item has the form of a class_ref structure. The class_ref 
structure is defined as part of the CONSTANT_Classref_info structure 
("CONST ANT_Classref ' on page 64). The interface jnfo structure ref- 
erenced by the interface item represents an interface implemented by this 
class. 



count 

The count item indicates the number of entries in the index array. 

index 

The index item is an array that maps declarations of interface methods to 
the implementations in this class. It is a representation of a all of the 
methods declared by the interface and its superinterfaces. Entries in the 
index array must be ordered such that the token of the declared interface 
method is equal to the index. The token value is that assigned to the 
method within the scope of the interface definition and its superinter- 
faces, not within the scope of this class. 
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The values in the index array represent the tokens of the implementation 
of the interface method. This token value is in the scope of this class. 



8 Method Component 

The Method Component describes each of the methods declared in this package, except 
<clinit> methods and interface method declarations. The exception handlers associated with 
each method are also described. The Method Component is represented by the following 
structure: 

method_component { 
u1 tag 
u2 size 

u1 handlers_count 

exception_handler_info exception_handlers[handlers_count] 
method_info methodsQ 

} 

The items in the method_component structure are as follows: 
tag 

The tag item has the value COMPONENTJv1ethod(7). 

size 

The size item indicates the number of bytes in the method_component structure, 
excluding the tag and size items. 

handlers_count 

The handlers_count item represents the number of entries in the 
exception_handlers array. 

exception_handlersQ 

The exceptionjiandlers item represents an array of 8-byte 

exception Jiandlerjnfo structures. Each exception_handler_info structure 

represents a catch or finally block defined in a method of this package. 

Entries in the exception_handlers array are sorted in ascending order by the dis- 
tance between the beginning of the Method Component to the endpoint of each 
active exception handler range in the methods item. 

methodsQ 

The methods item represents an array of variable-length methodjnfo structures. 
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Each entry represents a method declared in a class or interface of this package. 
<clinit> methods and interface method declaration are not included; all other 
abstract methods are. 



6.8. 1 exception JiandleMnfo 

The exceptionjiandlerjnfo structure is defined as follows: 

exception Jiandler info { 
u2 start_offset 
u2 activejength 
u2 handler_offset 
u2 catch Jypejndex 

} 

The items in the exception_handler_info structure are as follows: 

start_offset t activejength 

The activejength item is encoded to indicate whether the active range of this 
exception handler is nested within another exception handler. The high bit of the 
activejength is equal to 1 if the active range is not contained within another 
exception handler, and this exception handler is the last handler applicable to the 
active range. The high bit is equal to 0 if the active range is contained within the 
active range of another exception handler, or there are successive handlers applica- 
ble to the same active range. 

end_offset is defined as start_offset plus activejength & 0x7FFF. 

The start_offset item and end_offset are byte offsets into the info item of the 
Method Component. They indicate the ranges in a bytecode array at which the 
exception handler is active. The value of the start_offset must be a valid offset 
into a bytecode array to the opcode of an instruction. The value of the end_offset 
either must be a valid offset into a code array of the opcode of an instruction or 
must be equal to a method's bytecode count, the length of the code array. The 
value of the start_offset must be less than the value of the end_offset. 

The start_offset is inclusive and the endj>ffset is exclusive; that is, the exception 
handler must be active while the execution address is within the interval 
(start_offset ( end_offset). 

handler_offset 

The handler_offset item represents a byte offset into the info item of the Method 
Component. It indicates the start of the exception handler. The value of the item 
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must be a valid offset into a method's bytecode array to an opcode of an instruc- 
tion, and must be less than the value of the method's bytecode count. 

catchjypejndex 

If the value of the catch_type_index item is non-zero, it must be a valid index 
into the constant_pool table. The constant_pool entry at that index must be a 
CONSTANT_Classrefjnfo structure, representing the class of the exception 
caught by this exception_handlers table entry. 

If the exception_handlers table entry represents a finally block, the value of the 
catch_type_index item is zero. In this case the exception handler is called for all 
exceptions that are thrown within the start_offset and end ojfset range. 



!.2 methodinfo 

The method info structure is defined as follows: 



method_info { 

method_headerJnfo methodjieader 
u1 bytecodesQ 

} 



The items in the methodjnfo structure are as follows: 
method_header 

The method_header item represents either a method_headeMnfo or 
extended_method_headerjnfo structure: 

method_headerjnfo { 
u1 bitfield { 
bit[4] flags 
bit[4] max_stack 

} 

u1 bitfield { 
bit[4] nargs 
bit[4] maxjocals 

} 

} 

extended_method_header_info { 
u1 bitfield { 
bit[4] flags 
bit[4] padding 

u1 max stack 
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u1 nargs 

u1 max locals 

} 

The items of the method_header_info and extended_method_headerjnfo structures are 
as follows: 

flags 

The flags item is a mask of modifiers defined for the method. Valid flag values 
are shown in the following table. 



table 6-« Method flags 



Flags 


Values 


ACC_EXTENDED 
AC C_AB S T RAC T 


0x8 
0x4 



The value of the ACC_EXTENDED flag must be one if the methodjieader is 
represented by an extended jmethod_headerjnfo structure. Otherwise the 
value must be zero. 

The value of the ACC_ABSTRACT flag must be one if this method is defined as 
abstract. In this case the bytecodes array must be empty. If the method is not 
abstract the value of the ACC_ABSTRACT flag must be zero. 

. The Java Card Virtual Machine reserves all other flag values. Their values must 
be zero. 

padding 

The padding item has the value of zero. This item is only defined for the 
extended_method_headerjnfo structure. 

max_stack 

The max_stack item indicates the maximum number of 16-bit cells required on 
the operand stack during execution of this method. 

Stack entries of type int are represented in two 16-bit cells, while all others are rep- 
resented in one 16-bit cell. 

nargs 

The nargs item indicates the number of 16-bit cells required to represent the 
parameters passed to this method, including the this pointer for non-static meth- 
ods. 

Parameters of type int are represented in two 16-bit cells, while all others are rep- 
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resented in one 16-bit cell, 
maxjocals 

The maxjocals item indicates the number of 16-bit cells required to the local 
variables declared by this method, not including the parameters passed to the 
method on invocation. 



Note - Unlike in Java Card CAP files, in Java class files maxjocals includes 
both the local variables declared in a method and the parameters passed to a 
method. 

Local variables of type int are represented in two 16-bit cells, while all others are 
represented in one 16-bit cell. The number of cells required for overloaded local 
variables is two if one or more of the overloaded variables is of type int. 

codeQ 

The code item represents an array of Java Card bytecodes that implement the 
method. 



9 Static Field Component 

The Static Field Component contains all of the information required to create and initialize 
an image of the static fields defined in this package. Final static fields of primitive types are 
not represented in this component. Instead these compile-time constants occur inline in Java 
Card instructions. 

The ordering constraints associated with the static field image are as shown in the following 
figure. Reference-types occur first in the image. Arrays initialized through Java <clinit> 
methods occur first, and primitive types initialized to non-default values occur last. 



reference types 


arrays of primitive types initialized by <clinit> methods 


reference types initialized to null 


primitive types 


primitive types initialized to default values 


primitive types initialized to non-default values 



FIGURE 6-1 Static Field Order Map 



The number of bytes used to represent each field type in the static field image is shown in 
the following table. 
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TABLE 6-7 Static Field Sizes 



Type 


Bytes 


boolean 


l 


byte 


1 


short 


2 


int 


4 


reference 


2 



The static_field_component structure is defined as: 
static_field_component { 
u1 tag 
u2 size 
u2 byte_count 
u2 reference_count 
u2 array_init count 

a rrayjn it_infb arrayj n it[array_in it_cou nt] 

u2 default_value_count 

u2 non_default_value_count 

u1 non_default_values[non_default_values_count] 

} 

The items in the static_field_component structure are as follows: 
tag 

The tag item has the value COMPONENT_StaticField(8). 

size 

The size item indicates the number of bytes in the static_field_component struc- 
ture, excluding the tag and size items. 

byte_count 

The byte_COUnt item indicates the number of bytes required to represent the 
image of the static fields defined in this package. The number of bytes required to 
represent each type is shown in the previous table. 

The value of the byte_count item does not include the number of bytes require to 
represent the array instances defined in the Static Field Component. 

reference_count 

The reference_count item indicates the number of reference-type static fields 
defined in this package. 
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array_init_count 

The array_init_count item indicates the number of elements in the arrayjnit 
array. In CAP files that define a library package the value of array_init_count 
must be zero. 

arrayjnitQ . 

The arrayjnit item represents an array of arrayjnitjnfo structures that specify 
the initial array values of final static fields of arrays of primitive types. These ini- 
tial values are indicated in Java <clinit> methods. The arrayjnitjnfo structure 
is defined as: 

arrayjnitjnfo { 
u1 type 
u2 count 
u1 values[countJ 

} 

The type item represents the type of the primitive array. Valid values are shown in 
the following table. 



TABLE 6-8 Array Types 



Type 


Value 


boolean 


0 


byte 


1 


short 


2 


int 


4 



The count item represents the number of elements in the values array. 

This value of the count item is not the same as the number of elements in the array 
of the final static field. The number of elements in the array is equal to the count 
item divided by the number of bytes required to represent the static field type 
(table 6-7) indicated by the type item. 

The values array represents a byte array representing the initial values of the static 
field array. 

default_value_count 

The default_value_count item indicates the number of bytes required to initialize 
the set of static fields that are to be initialized to default values. The number of 
bytes require for each static field type is equal to the size in bytes of the type is 
shown in TABLE 6-7. 
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non_default_value_count 

The non_default_value_count item represents the number elements in the 
non_default_values array. 

of bytes of initial values primitive- type static fields initialized to non-default val- 
ues. This value is number of elements in the non_default_values array item. 

non_defau1t_values[] 

The non_default_values item represents an array of bytes of non-default initial 
values. The number of entries in the array for each static field type is equal to the 
size in bytes of the type as shown in TABLE 6-7. 



Reference Location Component 

The Reference Location Component represents lists of offsets into the Method Component to 
operands that contain indices into the constantjpool table. Some of the indices are 
represented in one-byte values while other are represented in two-byte values. The structure 
is defined as: 

referencejocation_component { 

u1 tag 

u2 size 

u2 byte_index_count 

u 1 offsets_to_byte jndices[byte_index__count] 
u2 byte2_index_count 

u1 offsets_to_byte2_indices[byte2jndex_count] 



The items of the referenceJocation_component structure are as follows: 
tag 

The tag item has the value COMPONENT_ReferenceLocation(9). 

size 

The size item indicates the number of bytes in the 

reference_location_component structure, excluding the tag and size items. 

bytejndex_count 

The byte_index_COlint item represents the number of elements in the 
offsets_to_bytejndices array. 
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off sets_to_bytejnd icesQ 

The offsets_to_byte_indices item represents an array of 1-byte jump offsets into 
the info item of the Method Component to each 1-byte constant_pool table index. 
Each entry represents the number of bytes (or distance) between the previous 
index to the next. If the distance is greater than or equal to 255 then there are n 
entries equal of 255 in the array, where n is equal to the distance divided by 255. 
The nth entry of 255 is followed by an entry containing the value of distance mod- 
ulo 255. An example of the jump offsets in an off sets Jo_byte_ind ices array, 
given a set of offsets to 1-byte contant pool references, is shown in Table 6-9, 
"One-byte Reference Location Example". 



TABLE 6-9 One-byte Reference Location Example 



Instruction 


Offset to 
Operand 


Jump Offset 


getfield_a 0 


10 


10 


putfield_b 2 


65 


55 






255 






255 


getfield_s 1 


580 


5 






255 


putfield_a 0 


835 


0 


getfield_i 3 


843 


8 



All one-byte constant _pool table indices in the Method Component must be rep- 
resented in offsets_to_byte Jndices array. 

byte2_index_count 

The byte2 jndex_count item represents the number of elements in the 
offsets_to_byte2jndices array. 

offsets_to_byte2_indicesQ 

The offsets_to_byte2 jndices item represents an array of 1-byte jump offsets 
into the info item of the Method Component to each 2-byte constant_pool table 
index. Each entry represents the number of bytes (or distance) between the previ- 
ous index to the next. If the distance is greater than or equal to 255 then there are n 
entries equal of 255 in the array where n is equal to the distance divided by 255. 
The nth entry of 255 is followed by an entry containing the value of distance mod- 
ulo 255. 

An example of the jump offsets in an offsets_to_byte_indices array, given a set of 
offsets to 1-byte contant pool references, is shown in Table 6-9, u One-byte Refer- 
ence Location Example". The same example applies to the 
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offsets_to_byte2_indices table if the instructions are changed to those with 2 -byte 
constant pool indices. 

All two-byte constantjDOOl table indices in the Method Component must be rep- 
resented in offsets_tO_byte2_indices array, including those represented in 
catch_type_index items of the exception_handlerjnfo table. 



Export Component 

The Export Component describes all elements in this package that other packages may 
reference directly. If this CAP file does not contain an Applet Component, the Export 
Component includes entries for all public classes. Furthermore, for each public class it 
includes entries for all public and protected static methods, and all public and protected static 
fields. The set of static fields does not include primitive final static fields (compile-time 
constants). Packages that reference instance fields and non-special virtual methods in this 
package do so indirectly through class references and field or method tokens, and are 
therefore not represented in the Export Component. 

If CAP file contains an Applet Component, the Export Component includes only entries for 
all public interfaces that are shareable. An interface is sharable if and only if it is the 
javacard.framework.Shar able interface or implements (directly or indirectly) that interface. 



Note - The restriction on exportable functionality is imposed by the firewall as defined in 
the Java Card Runtime Environment 2.1 specifications. 



The Export Component is represented by the following structure: 

export_component { 
u1 tag 
u2 size 

u2 class_count 

class_export jnfo { 

u2 class_offset 

u1 static_field_count 

u1 staticjnethod count 

u2 static Jleldj)ffsets[static_field_count] 

u2 static_method_offsets[static_method_countJ 

} class_exports[class_count] 

} 

The items of the ex portico mpon en t structure are as follows: 
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tag 



The tag item has the value COMPONENT_Export(10). 

size 

The size item indicates the number of bytes in the export_component structure, 
excluding the tag and size items. 

class_count 

The class_count item represents the number of public classes in this package. It 
indicates the number of elements in the class_exports array. 

class_exportsn 

The class_exports item represents a variable-length table of class_export_info 
structures. The table contains an entry for each of the public classes defined in this 
package. An index into the table to a particular element must be equal to the token 
value of the class. 

The items in the class_exportjnfo structure are: 
class_offset 

The class_offset item represents a byte offset into the info item of the Class Com- 
ponent to a classjnfo structure. The class jnfo structure at that offset must rep- 
resent the exported class. 

static_field_count 

The static_field_count item represents the number of elements in the 
static_field_offsets array. This value indicates the number of public and pro- 
tected static fields defined in this class, excluding final static fields of primitive 
types. 

static_method_count 

The static_method_count item represents the number of elements in the 
static_method_offsets array. This value indicates the number of public and pro- 
tected static methods and constructors defined in this class. 

static_field_offsetsQ 

The static_field_offset item represents an array of 2-byte offsets to a static field 
in the static field image defined by the Static Field Component. The static field 
defined at each offset must represent the exported field with the token value equal 
to the index to the entry in the static_field_offsets array. 



Java Card Virtual Machine 2.1 Specification • January 29, 1999 



static_method_offsetsQ 

The static jnethod_offset item represents a table of 2-byte offsets into the info 
item of the Method Component to a methodjnfo structure. The method_info 
structure at each offset must represent the exported method with the token value 
equal to the index to the entry in the static_method_offsets array. 



6.12 Descriptor Component 

The Descriptor Component provides sufficient information to parse and verify all elements 
of the CAP file. The Descriptor Component is represented by the following structure: 

descriptor_component { 
u1 tag 
u2 size 

u2 class_count 

class_descriptorjnfo classes[class_count] 
type_descriptorjnfo types 

} 

The items of the descriptor_component structure are as follows: 
tag 

The tag item has the value COMPONENTJDescriptor(l 1). 

size 

The size item indicates the number of bytes in the descriptor_component struc- 
ture, excluding the tag and size items. 

class_count 

The class_count item represents the number of class_descriptor_info structures 
in the classes array. 

classesQ 

The classes item represents a table of variable-length class_descriptor_info 
structures. Each class and interface defined in this package is represented in the 
table. 

types 

The types item represents a type jjescriptorjnfo structure. 
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12.1 class_descriptor_info 

The class_descriptorjnfo structure is used to describe a Java class or interface: 
class_descriptor_jnfo { 
u1 token 
u1 access_flags 
class_ref this_class_ref 
u1 interface_count 
u2 field_count 
u2 method_count 

class_ref interfaces [interface_count] 
field_descriptorjnfo fields[field_count] 
method_descriptorjnfo methods[method_count] 

} 

The items of the class_descriptor_info structure are as follows: 
token 

The token item represents the class token of this class or interface. If this class is 
private or package- visible it does not have a token assigned. In this case the value 
of the token item must be OxFF. 

access_flags 

The access_flags item is a mask of modifiers used to describe the access permis- 
sion to and properties of this class. The access Jlags modifiers for classes are 
shown in the following table. 



table 6-10 Class Access and Modifier Flags 



Name 


Value 


ACC_PUBLIC 


0x01 


ACC_FINAL 


0x10 


ACCJNTERFACE 


0x40 


ACC_ABSTRACT 


0x80 







The Java Card Virtual Machine reserves all other flag values. Their values must 
be zero. 

this_class_ref 

The this_class_ref item is a class_ref structure indicating the location of the 
classjnfo structure in the Class Component ("Class Component" on page 70). 
The class_ref structure is defined as part of the CONSTANT_Classref_info 
structure ("CONSTANT Classref on page 64). 

interface_count 

The interface_COunt item is represents the number of interfaces implemented by 
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this class. 
field_count 

The field_count item represents the number of field_descriptorjnfo structures in 
the fields array. It is the number of fields defined in this class. 

method_count 

The method_count item represents the number of method_descriptorjnfo 
structures in the methods array. It is the number of methods declared or defined 
in this class or interface. 

interfaces Q 

The interface_refs item represents an array of interfaces implemented by this 
class. The elements in the array are class_ref structures indicating the location of 
the classjnfo structure in the Class Component ("Class Component" on 
page 70). The class_ref structure is defined as part of the 
CONSTANT_Classrefjnfo structure ("CONSTANT Classref* on page 64). 

fieldsD 

The fields item represents a table of variable-length field_descriptor_info struc- 
tures. 

methods[] 

The methods item represents a table of variablejength method_descriptor _info 
structures. 



6.12.2 field_descriptor_info 

The field_descriptor_info structure is used to describe a Java field: 
field_descriptor_info { 
u1 token 
u1 access_flags 
union { 

static_field_ref static_field 

instance_field_ref instance_field 
} field ref 
union"! 

u2 primitive_type 
u2 type_offset 

}type 

} 

The items of the field_descriptorjnfo structure is as follows: 
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token 



The token item represents the token of this field. If this field is private or pack- 
age-visible static field it does not have a token assigned. In this case the value of 
the token item must be OxFF. 

access_flags 

The access_flags item is a mask of modifiers used to describe the access permis- 
sion to and properties of the field. The access__flags modifiers for instance fields 
are shown in the following table. 



table e-11 Field Access and Modifier Flags 



Name 


Value 


ACC_PUBLIC 


0x01 


ACC_PRIVATE 


0x02 


ACC_PROTECTED 


0x04 


ACC_STATIC 


0x08 


ACC_FINAL 


0x10 



All of the access flags are the same as those defined in a Java class file. 

The Java Card Virtual Machine reserves all other flag values. Their values must 
be zero. 

fieldjref 

The field_ref item represents a reference to the field. If the ACC_STATIC flag is 
equal to 1, this item represents a static_field_ref as defined in the 
CONSTANT_StaticFieldref structure ("CONSTANT_StaticFieldref and 
CONSTANT_StaticMethodref ' on page 68). If the ACC_STATIC flag is equal to 
0, this item represents an instance_field_ref as defined in the 
CONSTANTJnstanceFieldref structure ("CONSTANTJnstanceFieldref, 
CONSTANT_VirtualMethodref, and CONSTANT_SuperMethodref * on 
page 66). 



The type item represents the type of the field, directly or indirectly. If the field is 
a primitive type (boolean, byte, short, or int) the high bit of this item is set and the 
type is specified using the values in the following table. Otherwise the type item 
represents a 15-bit offset into the type_descriptor table. The item at the offset in 
the type_descriptor table must represent the type of the field. 
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table 6-12 Primitive Type Descriptor Values 



Data Type 


Value 


boolean 


0x02 


byte 


0x03 


short 


0x04 


integer 


0x05 



6.12.3 method_descriptor_info 

The method_descriptor_info structure is used to describe a Java method: 

method_descriptorjnfo { 
u1 token 
u1 access_flags 
u2 method_offset 
u2 type_offset 
u2 bytecode_count 
u2 exception_handler_count 
u2 exception_handler_index 

} 

The items of the method_descriptorjnfo structure are as follows: 
token 

The token item represents the token of this method. If this method is a private or 
package-visible static or constructor method, or private virtual method it does not 
have a token assigned. In this case the value of the token item must be OxFF. 

access_flags 

The access_flags item is a mask of modifiers used to describe the access permis- 
sion to and properties of the method. The access_flags modifiers for methods 
are shown in the following table. 
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table 6-13 Method Access and Modifier Flags 



Name 


Value 


ACC_PUBLIC 


0x01 


ACC_PRIVATE 


0x02 


ACC_PROTECTED 


0x04 


ACC_STATIC 


0x08 


ACC_FINAL 


0x10 


ACC_ABSTRACT 


0x40 


ACC_INIT 


0x80 



All of the access flags are the same as those defined in a Java class file except the 
ACCJNIT flag. 

The ACCJNIT flag is set if the method descriptor identifies a constructor meth- 
ods. In Java a constructor method is recognize by the class file verifier by its 
name, <init>, but in Java Card the name is replaced by a token. These methods 
require special checks by a verifier. 

The Java Card Virtual Machine reserves all other flag values. Their values must 
be zero. 

method_offset 

The method_offset item represents a byte offset into the info item of the Method 
Component ("Method Component" on page 76) to a method jnfo structure. The 
method info structure must represent this method. 

If the class_descriptor_info structure that contains this 
method_descriptor_info structure represents an interface, the value of the 
method_offset item must be zero. 

type_offset 

The type_offset item must be a valid offset into the type_descriptor_info array. 
The type described at that offset represents the signature of the method. 

bytecode_count 

The bytecode_COunt item represents the number of bytecodes in the method. 

exception_handler_count 

The exception Jiandler_count item represents the number of exception handler 
implemented by this method. 

exception_handlerjndex 

The exception_handlerjndex item represents the index to the first 
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exception_handlers table entry of the method jnfb structure that is imple- 
mented by this method. Succeeding exception_handlers table entries, up to the 
value of the exception_handler_count item, are also exception handlers imple- 
mented by this method. 



6.12.4 type_descriptor_info 

The type_descriptor_info structure represents the types of fields and signatures of methods 
as follows: 

type_descriptor_info { 
u2 cp_count 

u2 constant_types[cp_types] 
{ u1 nibble_count; 

u1 type[(nibble_count+1 ) / 2]; 
} type_desc[] 

} 

The structure type_descriptorjnfo structure contains the following elements: 
cp_COUnt 

The cp_count value represents the number of entries in the constantjDOOi table. 
constant_typesQ 

The constanMypes item represents an array of offsets to type_descriptor struc- 
tures corresponding to the parallel entries in the constant_pool table. If the corre- 
sponding constant_pool table entry does not have an associated type, the value of 
the entry in the constanMypes array item is OxFFFF. 

type_descO 

The type_desc item represents an array of variable-length type descriptor struc- 
tures. These descriptors represent the types of fields and signatures of methods. 
The elements in the structure are: 

nibble_count 

The nibble_count value represents the number of nibbles in the type 
array. 

typeQ 

The type array contains an encoded description of the type composed of 
individual nibbles. If nibble_count item is an odd number, the last nibble 
must be 0x0. The values of the type descriptor rubbles are defined in the 
following table. 
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table e-14 Type Descriptor Values 



Type 


Value 


void 


0x1 


boolean 


0x2 


byte 


0x3 


short 


0x4 


int 


0x5 


objectref 


0x6 


array of boolean 


OxA 


array of byte 


OxB 


array of short 


OxC 


array of int 


OxD 


array of objectref 


OxE 



Class reference types are described using the class nibble 0x6, followed by a 2-byte (4- 
nibble) classjref structure. The classjref structure is defined as part of the 
CONSTANT_Classref_jnfo structure ("CONST ANT_Classref" on page 64). For example, 
a field of type reference to pl.cl in a CAP file defining package pO is described as: 



0x6 


<pl> 


<cl> 


0x0 


objectref 


package token 
{high bit on) 


class 
token 


padding 



The following are examples of the array-types: 



byte [ ] 


OxB 


0x0 








array of 
byte 


padding 
















pl.cl [] 


OxE 


<pl> 


<cl> 


0x0 




array of 
objectref 


package 
token 
(high bit 
on) 


class 
token 


padding 



Method signatures are encoded in the same way, with the last nibble indicating the return 
type of the method, for example: 



<>v 


0x1 


0x0 








void 


padding 
















(Lpl.cl; )S 


0x6 


<pl> 


<cl> 


0x4 




objectref 


package token 
(high bit on) 


class 
token 


short 
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CHAPTER 7 



Java Card Virtual Machine 
Instruction Set 



A Java Card Virtual Machine instruction consists of an opcode specifying the operation to be 
performed, followed by zero or more operands embodying values to be operated upon. This 
chapter gives details about the format of each Java Card Virtual Machine instruction and the 
operation it performs. 



The description of each instruction is always given in the context of Java Card Virtual 
Machine code that satisfies the static and structural constraints of Chapter 6, "The Cap File 
Format." 

In the description of individual Java Card Virtual Machine instructions, we frequently state„ 
that some situation "must" or "must not" be the case: "The value2 must be of type int." t 
The constraints of Chapter 6, "The Cap File Format" guarantee that all such expectations 
will in fact be met. If some constraint (a "must" or "must not") in an instruction description 
is not satisfied at run time, the behavior of the Java Card Virtual Machine is undefined. 



In addition to the opcodes of the instructions specified later this chapter, which are used in 
Java Card CAP files (see Chapter 5, "The Cap File Format"), two opcodes are reserved for 
internal use by a Java Card Virtual Machine implementation. If Sun extends the instruction 
set of the Java Card Virtual Machine in the future, these reserved opcodes are guaranteed 
not to be used. 



7.1 



Assumptions: The Meaning of "Must 





95 



The two reserved opcodes, numbers 254 (Oxfe) and 255 (Oxff), have the mnemonics 
impdepl and impdep2, respectively. These instructions are intended to provide "back 
doors" or traps to implementation-specific functionality implemented in software and hard- 
ware, respectively. 

Although these opcodes have been reserved, they may only be used inside a Java Card Vir- 
tual Machine implementation. They cannot appear in valid CAP files. 



A Java Card Virtual Machine throws an object that is an instance of a subclass of the class 
VirtualMachineError when an internal error or resource limitation prevents it from 
implementing the semantics of the Java Language. The Java Card Virtual Machine specifi- 
cation cannot predict where resource limitations or internal errors may be encountered and 
does not mandate precisely when they can be reported. Thus, any of the virtual machine 
errors listed as subclasses of VirtualMachineError in Section 2.3.3.4, "Errors," on 
page 2-20 may be thrown at any time during the operation of the Java Card Virtual 
Machine. 



Instructions of the Java Card Virtual Machine throw an instance of the class SecurityEx- 
ception when a security violation has been detected. The Java Card Virtual Machine does 
not mandate the complete set of security violations which can or will result in an exception 
being thrown. However, there is a minimum set which must be supported. 

In the general case, any instruction which de-references an object reference must throw a 
SecurityExcept ion if the applet context in which the instruction is executing is different 
than the owning applet context of the referenced object. The list of instructions includes the 
instance field get and put instructions, the array load and store instructions, as well as the 
arraylength, invokeinterface, invokespecial, invokevirtual, checkcast, instanceof and 
athrow instructions. 

There are several exceptions to this general rule that allow cross-context use of objects or 
arrays. These exceptions are detailed in Chapter 6 of the Java Card Runtime Environment 
Specification, An important detail to note is that any cross-context method invocation will 
result in a context switch. 

The Java Card Virtual Machine may also throw a SecurityException if an instruction 
violates any of the static constraints of Chapter 6, "The Cap File Format." The Java Card 
Virtual Machine specification does not mandate which instructions must implement these 
additional security checks, or to what level. Therefore, a SecurityException may be 



3 



Virtual Machine Errors 



4 



Security Exceptions 
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thrown at any time during the operation of the Java Card Virtual Machine. 



7.5 The Java Card Virtual Machine Instruction 
Set 

Java Virtual Machine instructions are represented in this chapter by entries of the form 
shown in the figure below, an example instruction page, in alphabetical order and each 
beginning on a new page. 



mnemonic 


Short description of the instruction 


Format 


mnemonic 

operandi 

operand2 


Forms 


mnemonic = opcode 


Stack 


value I, value! => 
value3 


Description 


A longer description detailing constraints on operand stack contents or constant pool 
entries, the operation performed, the type of the results, etc. 


Runtime Exceptions 

If any runtime exceptions can be thrown by the execution of an instruction they are 
set off one to a line, in the order in which they must be thrown. 




Other than the runtime exceptions, if any, listed for an instruction, that instruction 
must not throw any runtime exceptions except for instances of virtualMachineEr- 
ror or its subclasses. 


Notes 


Comments not strictly part of the specification of an instruction are set aside as notes 
at the end of the description. 



FIGURE 7-1 An example instruction page 



Each cell in the instruction format diagram represents a single 8-bit byte. The instruction's 
mnemonic is its name. Its opcode is its numeric representation and is given in both decimal 
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and hexadecimal forms. Only the numeric representation is actually present in the Java Card 
Virtual Machine code in a CAP file. 

Keep in mind that there are "operands" generated at compile time and embedded within 
Java Card Virtual Machine instructions, as well as "operands" calculated at run time and 
supplied on the operand stack. Although they are supplied from several different areas, ail 
these operands represent the same thing: values to be operated upon by the Java Card Vir- 
tual Machine instruction being executed. By implicitly taking many of its operands from its 
operand stack, rather than representing them explicitly in its compiled code as additional 
operand bytes, register numbers, etc., the Java Card Virtual Machine's code stays compact. 

Some instructions are presented as members of a family of related instructions sharing a 
single description, format, and operand stack diagram. As such, a family of instructions 
includes several opcodes and opcode mnemonics; only the family mnemonic appears in the 
instruction format diagram, and a separate forms line lists all member mnemonics and 
opcodes. For example, the forms line for the sconst_<s> family of instructions, giving 
mnemonic and opcode information for the two instructions in that family (sconstO and 
sconst_!), is 

Forms sconstj) = 3 (0x3), 
sconst_! = 4 (0x4) 

In the description of the Java Card Virtual Machine instructions, the effect of an instruc- 
tion's execution on the operand stack of the current frame is represented textually, with the 
stack growing from left to right and each word represented separately. Thus, 

Stack. . . , value 1 , value2 => 
result 

shows an operation that begins by having a one- word value! on top of the operand stack 
with a one- word value! just beneath it. As a result of the execution of the instruction, 
valuel and value! are popped from the operand stack and replaced by a one-word result, 
which has been calculated by the instruction. The remainder of the operand stack, repre- 
sented by an ellipsis (...), is unaffected by the instruction's execution. 

The type int takes two words on the operand stack. In the operand stack representation, 
each word is represented separately using a dot notation: 

Stack. . value!. word!, value !.word2, value2.word!, value2.word2 => 
result.word!, resultword2 

The Java Card Virtual Machine specification does not mandate how the two words are used 
to represent the 32-bit int value; it only requires that a particular implementation be inter- 
nally consistent. 
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aaload 



Load reference from array 

Format _ ^ 

aaload 

Forms 

aaload = 36 (0x24) 

Stack 

. . arrayref index => 
value 

Description 

The arrayref must be of type reference and must refer to an array whose components are 
of type reference. The index must be of type short. Both arrayref and index are popped 
from the operand stack. The reference value in the component of the array at index is 
retrieved and pushed onto the top of the operand stack. 

Runtime Exceptions 

If arrayref "is null, aaload throws a NullPointerException. 

Otherwise, if index is not within the bounds of the array referenced by arrayref, the aaload 
instruction throws an ArraylndexOutOf BoundsException. 
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aastore 



Store into reference array 

Format 



aastore 



Forms 

aastore = 55 (0x37) 

Stack 

. . ., arrayref index, value : 



Description 

The arrayref must be of type reference and must refer to an array whose components are 
of type reference. The index must be of type short and the value must be of type ref- 
erence . The arrayref, index and value are popped from the operand stack. The refer- 
ence value is stored as the component of the array at index. 

The type of value must be assignment compatible with the type of the components of the 
array referenced by arrayref. Assignment of a value of reference type S (source) to a vari- 
able of reference type r (target) is allowed only when the type S supports all of the opera- 
tions defined on type r. The detailed rules follow: 

n If S is a class type, then: 

a If T is a class type, then S must be the same class as r, or S must be a subclass of r 9 

a If T is an interface type, S must implement interface r. 

n If 5 is an array type, namely the type SC[ ) , that is, an array of components of type SC, 
then: 

a If r is a class type, T must be Ob j ect, or: 

a If T is an array type, namely the type TC[ ] , an array of components of type rc, 
then either TC and SC must be the same primitive type, or 

n TC and SC must both be reference types with type SC assignable to TC, by these 
rules. 

S cannot be an interface type, because there are no instances of interfaces, only instances of 
classes and arrays. 

Runtime Exceptions 

. If arrayref is null, aastore throws a NullPointerException. 

Otherwise, if index is not within the bounds of the array referenced by arrayref the aastore 
instruction throws an ArraylndexOutOf BoundsException. 

Otherwise, if arrayref is not null and the actual type of value is not assignment compatible 
with the actual type of the component of the array, aastore throws an ArrayStoreExcep- 
tion. 
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aeons t_null 

Push null 

Format 



aconst null 



Forms 

aconst _null = 1 (0x1) 

Stack 

... => 
null 

Description 



Push the null object reference onto the operand stack. 
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aload 



Load reference from local variable 



Format 

Forms 
Stack 

Description 
Notes 



aload 



index 



aload = 21(0x15) 



objectref 

The index is an unsigned byte that must be a valid index into the local variables of the cur- 
rent frame. The local variable at index must contain a reference. The objectref in the local 
variable at index is pushed onto the operand stack. 

The aload instruction cannot be used to load a value of type returnAddress from a local 
variable onto the operand stack. This asymmetry with the astore instruction is intentional. 
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aload <n> 



Load reference from local variable 



Format 



aload <n> 



Forms 



aload 
aload 
aload 
aload 



0 
I 
2 
3 



24 (0x18) 

25 (0x19) 

26 (Oxla) 

27 (Oxlb) 



Stack 



... => 

objectref 



Description 



The <n> must be a valid index into the local variables of the current frame. The local vari- 
able at <n> must contain a reference. The objectref in the local variable at <n> is 
pushed onto the operand stack. 



An aload_<n> instruction cannot be used to load a value of type returnAddress from a 
local variable onto the operand stack. This asymmetry with the corresponding astore_<n> 
instruction is intentional. 

Each of the aload_<n> instructions is the same as aload with an index of </i>, except that 
the operand <n> is implicit. 



Notes 
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anewarray 



anewarray 



indexbytel 
indexbyte2 



Create new array of reference 

Format 
Forms 

anewarray = 145 (0x91) 

Stack 

count 
array ref 

Description 

The count must be of type short. It is popped off the operand stack. The count represents 
the number of components of the array to be created. The unsigned indexbytel and 
indexbytel are used to construct an index into the constant pool of the current package, 
where the value of the index is (indexbytel « 8) | indexbytel. The item at that index in the 
constant pool must be of type CONSTANT_classref , a reference to a class or interface 
type. The reference is resolved. A new array with components of that type, of length count, 
is allocated from the heap, and a reference arrayref to this new array object is pushed 
onto the operand stack. All components of the new array are initialized to null, the default 
value for reference types. 

Runtime Exception 

If count is less than zero, the anewarray instruction throws a NegativeArraySizeEx- 
ception. 
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areturn 

Return reference from method 

Format 

areturn 

Forms 

areturn = 119(0x77) 

Stack 

objectref 
[empty] 

' Description 

The objectref must be of type reference. The objectref is popped from the operand stack 
of the current frame and pushed onto the operand stack of the frame of the invoker. Any 
other values on the -operand stack of the current method are discarded. 

The virtual machine then reinstates the frame of the invoker and returns control to the 
invoker. 
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arraylength 



arraylength 

Get length of array 

Format 
Forms 
Stack 

Description 



arraylength = 146 (0x92) 

arrayref^ 
length 



The arrayref must be of type reference and must refer to an array. It is popped from the 
operand stack. The length of the array it references is determined. That length is pushed 
onto the top of the operand stack as a short. 

Runtime Exception 

If arrayref is null, the arraylength instruction throws a NullPointerException. 
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astore 

Format 

Forms 
Stack 



Store reference into local variable 



astore 



index 



astore = 40 (0x28) 
objectref 



Description 

The index is an unsigned byte that must be a valid index into the local variables of the cur- 
rent frame. The objectref on the top of the operand stack must be of type returnAddress 
or of type reference. The objectref is popped from the operand stack, and the value of the 
local variable at index is set to objectref. 

Notes 

The astore instruction is used with an objectref of type returnAddress when implement- 
ing Java's finally keyword. The aload instruction cannot be used to load a value of type 
returnAddress from a local variable onto the operand stack. This asymmetry with the 
astore instruction is intentional. 
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astore 

Format 
Forms 

Stack 

Description 
Notes 



<n> 

Store reference into local variable 



astore _<n> 



astore J) = 43 (0x2b) 
astorejt = 44 (0x2c) 
astore _2 = 45 (0x2d) 
astore J = 46 (0x2e) 

objectref => 



The <n> must be a valid index into the local variables of the current frame. The objectref 
on the top of the operand stack must be of type returnAddress or of type reference. It 
is popped from the operand stack, and the value of the local variable at <n> is set to objec- 
tref. 

An astore_<n> instruction is used with an objectref of type returnAddress when imple- 
menting Java's finally keyword. An aload_<n> instruction cannot be used to load a 
value of type returnAddress from a local variable onto the operand stack. This asymme- 
try with the corresponding astore_<n> instruction is intentional. 

Each of the aload_<n> instructions is the same as aload with an index of <«>, except that 
the operand <n> is implicit. 
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a throw 



Throw exception or error 

Format 

a throw 

Forms 

athrow=\41 (0x93) 

Stack 

objectref^ 
objectref 

Description 

The objectref must be of type reference and must refer to an object which is an instance 
of class Throwable or of a subclass of Throwable. It is popped from the operand stack. 
The objectref is then thrown by searching the current frame for the most recent catch 
clause that catches the class of objectref or one of its superclasses. 

If a catch clause is found, it contains the location of the code intended to handle this 
exception. The pc register is reset to that location, the operand stack of the current frame is 
cleared, objectref is pushed back onto the operand stack, and execution continues. If no 
appropriate clause is found in the current frame, that frame is popped, the frame of its 
invoker is reinstated, and the objectref is rethrown. 

If no catch clause is found that handles this exception, the virtual machine exits. 
Runtime Exception 

If objectref is null, athrow throws a NullPointerException instead of objectref 
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baload 



Load byte or boolean from array 

Format _„ 

baload 

Forms 

baload =37 (0x25) 

Stack 

. . arrayref index => 
value 

Description 

The arrayref must be of type reference and must refer to an array whose components are 
of type byte or of type boolean. The index must be of type short. Both arrayref and 
index are popped from the operand stack. The byte value in the component of the array at 
index is retrieved, sign-extended to a short value t and pushed onto the top of the operand 
stack. 

Runtime Exceptions 

If arrayref is null, aaload throws a NullPointerException. 

Otherwise, if index is not within the bounds of the array referenced by arrayref the aaload 
instruction throws an ArraylndexOutOf BoundsException. 
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bastore 



Store into byte or boolean array 



Format 

Forms 

Stack 



bastore 



bastore = 56 (0x38) 



. . . , arrayref index, value : 



Description 

The arrayref must be of type reference and must refer to an array whose components are 
of type byte or of type boolean. The index and value must both be of type short. The 
arrayref, index and value are popped from the operand stack. The short value is truncated 
to a byte and stored as the component of the array indexed by index. 

Runtime Exceptions 

If arrayref is null, bastore throws a NullPointerException. 

Otherwise, if index is not within the bounds of the array referenced by arrayref the bastore 
instruction throws an ArraylndexOutOfBoundsException. 
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bipush 

Push byte 

Format 



bipush 
byte 



Forms 

bipush = 18 (0x12) 

Stack 

... => 

. . . , value. wordl, value. word2 

Description 

The immediate byte is sign-extended to an int, and the resulting value is pushed onto the 
operand stack. 

Notes 

If a virtual machine does not support the int data type, the bipush instruction will not be 
available. 
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bspush 

Push byte 

Format ^ 

bspush 
byte 

Forms 

bspush = 16(0x10) 

Stack 

... => 
value 

Description 



The immediate byte is sign-extended to a short, and the resulting value is pushed onto the 
operand stack. 
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checkcast 

Check whether object is of given type 

Format 

checkcast 

atype 
indexbytel 
indexbytel 

Forms 

checkcast = 148 (0x94) 

Stack 

objectref => 
objectref 

Description 

The unsigned byte atype is a code that indicates if the type against which the object is being 
checked is an array type or a class type. It must take one of the following values or zero: 



Array Type 


atype 


T_BOOLEAN 


10 


T_BYTE 


11 


T_SHORT 


12 


T_INT 


13 


T_RE FERENCE 


14 



If the value of atype is 10, 1 1, 12, or 13, the values of the indexbytel and indexbyte2 must 
be zero, and the value of atype indicates the array type against which to check the object. 
Otherwise the unsigned indexbytel and indexbytel are used to construct an index into the 
constant pool of the current package, where the value of the index is {indexbytel « 8) | 
indexbyte2. The item at that index in the constant pool must be of type 
CONSTANT_C la s s r e f , a reference to a class or interface type. The reference is resolved. If 
the value of atype is 14, the object is checked against an array type which is an array of 
object references of the type of the resolved class. If the value of atype is zero, the object is 
checked against a class or interface type which is the resolved class. 

The objectref must be of type reference. If objectref is null or can be cast to the speci- 
fied array type or the resolved class or interface type, the operand stack is unchanged; other- 
wise the checkcast instruction throws a ClassCastException. 

The following rules are used to detenriine whether an objectref that is not null can be cast 
to the resolved type: if S is the class of the object referred to by objectref 'and T is the 
resolved class, array or interface type, checkcast determines whether objectref cm be cast to 
type ras follows: 

n If S is an ordinary (non-array) class, then: 

0 If T is a class type, then S must be the same class as r, or a subclass of T. 
n If T is an interface type, S must implement interface T. 
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n If S is a class representing the array type SC[ } , that is, an array of components of type 
SC, then: 

n If r is a class type, then T must be Ob j ect. 

n If r is an array type TC[ ] , that is, an array of components of type TC, then one of the 
following must be true: 

a TC and type SC are the same primitive type. 

0 TC and SC are reference types, and type SC can be cast to TC by these runtime 
rules. 

S cannot be an interface type, because there are no instances of interfaces, only instances of 
classes and arrays. 

Runtime Exception 

If objectref cannot be cast to the resolved class, array, or interface type, the checjccast 
instruction throws a ClassCastException. 

Notes 

The checkcast instruction is fundamentally very similar to the instanceofmstrnztion. It dif- 
fers in its treatment of null, its behavior when its test fails {checkcast throws an exception, 
instanceof pushes a result code), and its effect on the operand stack. 

If a virtual machine does not support the int data type, the value of atype may not be 13 
(array type = t_int). 
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dup 

Format 

Forms 

Stack 

Description 
Notes 



Duplicate top operand stack word 



dup 



dup = 61 (0x3d) 

,..,word^> 
word 9 word 

The top word on the operand stack is duplicated and pushed onto the operand stack. 
The dup instruction must not be used unless word contains a 16-bit data type. 

Except for restrictions preserving the integrity of 32-bit data types, the dup instruction oper- 
ates on an untyped word, ignoring the type of data it contains. 
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dup_x 

Format 

Forms 
Stack 

Description 



Notes 



Duplicate top operand stack words and insert below 



dup_x 



dupjc = 63 (0x30 

, . ., wordN, . . wordM, . . . , wordl ^> 

wordM, wordl y wordN y wordM, wordl 

The unsigned byte mn is used to construct two parameter values. The high nybble, (mn & 
OxfD) » 4, is used as the value m. The low nybble, (mn & Oxf), is used as the value n. Per- 
missible values for m are 1 through 4. Permissible values for n are 0 and m through /n+4. 

For positive values of w, the top m words on the operand stack are duplicated and the copied 
words are inserted n words down in the operand stack. When n equals 0, the top m words 
are copied and placed on top of the stack. 

The dupjc instruction must not be used unless the ranges of words 1 through m and words 
m+1 through n each contain either a 16-bit data type, two 16-bit data types, a 32-bit data 
type, a 16-bit data type and a 32-bit data type (in either order), or two 32-bit data types. 

Except for restrictions preserving the integrity of 32-bit data types, the dupjc instruction 
operates on untyped words, ignoring the types of data they contain. 

If a virtual machine does not support the int data type, the permissible values for m are 1 or 
2, and permissible values for n are 0 and m through m+2. 
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dup2 

Format 

Forms 

Stack 

Description 



Notes 



Duplicate top two operand stack words 



dup2 



dup2 = 62 (0x3e) 

. . ., word2, wordl 

word2, wordl, word2, wordl 

The top two words on the operand stack are duplicated and pushed onto the operand stack, 
in the original order. 

The dup2 instruction must not be used unless each of wordl and word2 is a word that con- 
tains a 16-bit data type or both together are the two words of a single 32-bit datum. 

Except for restrictions preserving the integrity of 32-bit data types, the dup2 instruction 
operates on untyped words, ignoring the types of data they contain. 
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getf ield_<t> 



Fetch field from object 



Format 



getfield_<t> 



index 



Forms 



getfieldja 
getfieldjb 
getfield_s 
getfieldj 



131 (0x83) 
132(0x84) 

133 (0x85) 

134 (0x86) 



Stack 



. . . , objectref => 
value 

OR 

objectref => 

value.wordl , value,word2 



The objectref, which must be of type reference, is popped from the operand stack. The 
unsigned index is used as an index into the constant pool of the current package. The con- 
stant pool item at the index must be of type CONSTANT_InstanceFieldref , a reference 
to a class and a field token. If the field is protected, then it must be either a member of the 
current class or a member of a superclass of the current class, and the class of objectref must 
be either the current class or a subclass of the current class. 

The item must resolve to a field with a type that matches f, as follows: 

• a field must be of type reference 

• b field must be of type byte or type boolean 

• s field must be of type short 

• / field must be of type int 

The width of a field in a class instance is determined by the field type specified in the 
instruction. The item is resolved, detenriining the field offset. The value at that offset into 
the class instance referenced by objectref is fetched. If the value is of type byte or type 
boolean, it is sign-extended to a short. The value is pushed onto the operand stack. 



Runtime Exception 

If objectref 'is null, the getfield_<t> instruction throws a NullPointerException. 



If a virtual machine does not support the int data type, the getfieldj instruction will not be 



Description 



Notes 



available. 
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getf ield_<t>_this 

Fetch field from current object 



Format 



Forms 



Stack 



getfie!d_<t>Jhis 



index 



getfieldjijhis = 173 (Oxad) 
getfieldjbjhis = 174 (Oxae) 
getfieldjsjhis = 175 (Oxaf) 
getfieldjjhis = 176 (OxbO) 



value 

OR 



. . . , value, wordl, value. word2 

Description 

The currently executing method must be an instance method. The local variable at index 0 
must contain a reference objectref 'to the currently executing method's this parameter. 
The unsigned index is used as an index into the constant pool of the current package. The 
constant pool item at the index must be of type CONSTANT_lnstanceFieldref , a refer- 
ence to a class and a field token. If the field is protected, then it must be either a member 
of the current class or a member of a superclass of the current class, and the class of objec- 
tref must be either the current class or a subclass of the current class. 

The item must resolve to a field with a type that matches as follows: 

• a field must be of type reference 

• b field must be of type byte or type boolean 

• s field must be of type short 

• i field must be of type int 

The width of a field in a class instance is determined by the field type specified in the 
instruction. The item is resolved, determining the field offset. The value at that offset into 
the class instance referenced by objectref is fetched. If the value is of type byte or type 
boolean, it is sign-extended to a short. The value is pushed onto the operand stack. 

Runtime Exception 

If objectref is null, the getfield_<t> this instruction throws a NullPointerException. 



Notes 



If a virtual machine does not support the int data type, the getfieldjjhis instruction will 
not be available. 
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getf ield_<t>_w 

Fetch field from object (wide index) 

Format 

getfield_<t>_w 
indexbytel 
indexbyte2 

Forms 

getfieldjLjw = 169 (0xa9) 
getfield_b_w = 170 (Oxaa) 
getfxeldjjw =171 (Oxab) 
getfield_i_w = 172 (Oxac) 

Stack 

objectref => 
value 

OR 

objectref ^> 
. . . , value, word J , value. word2 

Description 

The objectref which must be of type reference, is popped from the operand stack. The 
unsigned indexbytel and indexbytel are used to construct an index into the constant pool of 
the current package, where the value of the index is (indexbytel « 8) | indexbyte2. The 
constant pool item at the index must be of type CONSTANT InstanceFieldref , a refer- 
ence to a class and a field token. The item must resolve to a field of type reference. If the 
field is protected, then it must be either a member of the current class or a member of a 
superclass of the current class, and the class of objectref must be either the current class or a 
subclass of the current class. 

The item must resolve to a field with a type that matches /, as follows: 

• a field must be of type reference 

• b field must be of type byte or type boolean 

• s field must be of type short 

• i field must be of type int 

The width of a field in a class instance is determined by the field type specified in the 
instruction. The item is resolved, detenriining the field offset. The value at that offset into 
the class instance referenced by objectref is fetched. If the value is of type byte or type 
boolean, it is sign-extended to a short. The value is pushed onto the operand stack. 

Runtime Exception 

If objectref 'is null, the getfield_<t> _w instruction throws a NullPointerException. 

Notes 

If a virtual machine does not support the int data type, the getfield_i_w instruction will not 
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be available. 
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getstatic_<t> 

Get static field from class 



Format 



Forms 



Stack 



getstatic_<t> 



indexbytel 
indexbyte2 



getstatic_a = 123 (0x7b) 
getstaticj* = 124 (0x7c) 
getstaticj = 125 (0x7d) 
getstaticj = 126 (0x7e) 



value 

OR 



Description 



Notes 



. . . , value. word!, value. word2 

The unsigned indexbytel and indexbyte2 are used to construct an index into the constant 
pool of the current package, where the value of the index is {indexbytel « 8) | indexbytel. 
The constant pool item at the index must be of type CONSTANT_StaticFieldref , a refer- 
ence to a static field. If the field is protected, then it must be either a member of the cur- 
rent class or a member of a superclass of the current class. 

The item must resolve to a field with a type that matches t, as follows: 

• a field must be of type reference 

• b field must be of type byte or type boolean 

• s field must be of type short 

• i field must be of type int 

The width of a class field is determined by the field type specified in the instruction. The 
item is resolved, determining the field offset. The item is resolved, determining the class 
field. The value of the class field is fetched. If the value is of type byte or type boolean, it 
is sign-extended to a short. The value is pushed onto the operand stack. 

If a virtual machine does not support the int data type, the getstaticj instruction will not 
be available. 
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goto 

Format 

Forms 
Stack 

Description 



Branch always 



goto 



branch 



goto= 112(0x70) 



No change 



The value branch is used as a signed 8-bit offset. Execution proceeds at that offset from the 
address of the opcode of this goto instruction. The target address must be that of an opcode 
of an instruction within the method that contains this goto instruction. 
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goto_w 

Format 

Forms 
Stack 

Description 



Branch always (wide index) 



gotojw 



branchbytel 
branchbyte2 



goto_w = 168 (0xa8) 



No change 



The unsigned bytes branchbytel and branchbyte2 are used to construct a signed 16-bit 
branchoffset, where branchoffset is {branchbytel « 8) | branchbytel Execution proceeds 
at that offset from the address of the opcode of this goto instruction. The target address must 
be that of an opcode of an instruction within the method that contains this goto instruction. 
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i2b 



Convert int to byte 



Format 

Forms 

Stack 

Description 



Notes 



i2b 



i2b - 93 (0x5d) 

value.wordl, value.word2 => 
result 

The value on top of the operand stack must be of type int. It is popped from the operand 
stack and converted to a byte result by taking the low-order 16 bits of the int value, and 
discarding the high-order 16 bits. The low-order word is truncated to a byte, then sign- 
extended to a short result. The result is pushed onto the operand stack. 

The i2b instruction performs a narrowing primitive conversion. It may lose information 
about the overall magnitude of value. The result may also not have the same sign as value. 

If a virtual machine does not support the int data type, the i2b instruction will not be avail- 
able. 
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i2s 



Convert int to short 



Format 

Forms 

Stack 

Description 
Notes 



i2s 



i2s = 94 (0x5e) 

value.wordJ , value.word2 => 
resu/r 

The value on top of the operand stack must be of type int. It is popped from the operand 
stack and converted to a short result by taking the low-order 16 bits of the int value and 
discarding the high-order 16 bits. The result is pushed onto the operand stack. 

The i2s instruction performs a narrowing primitive conversion. It may lose information 
about the overall magnitude of value. The result may also not have the same sign as value. 

If a virtual machine does not support the int data type, the i2s instruction will not be avail- 
able. 
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iadd 



Add int 



Format 

Forms 

Stack 

Description 



Notes 



1ST 



iadd = 66 (0x42) 

valuel. wordl, value l.word2, value2.wordl f value2.word2 => 
result.wordl , resultword2 

Both valuel and value2 must be of type int. The values are popped from the operand stack. 
The int result is valuel + value2. The result is pushed onto the operand stack. 

If an iadd instruction overflows, then the result is the low-order bits of the true mathemati- 
cal result in a sufficiently wide two's-complement format. If overflow occurs, then the sign 
of the result may not be the same as the sign of the mathematical sum of the two values. 

If a virtual machine does not support the int data type, the iadd instruction will not be 
available. 
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iaload 



Format 



Forms 



Stack 



Description 



Load int from array 
iaload 



iaload = 39 (0x27) 

. . ., arrayref index => 

value.wordl , value.word2 



The arrayref must be of type reference and must refer to an array whose components are 
of type int. The index must be of type short. Both arrayref and index are popped from the 
operand stack. The int value in the component of the array at index is retrieved and pushed 
onto the top of the operand stack. 

Runtime Exceptions 

If arrayref is null, aaload throws a NullPointerException. 

Otherwise, if index is not within the bounds of the array referenced by arrayref the aaload 
instruction throws an ArraylndexOutOf BoundsException. 



Notes 



If a virtual machine does not support the int data type, the iaload instruction will not be 
available. 
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iand 



Boolean AND int 



Format 

Forms 

Stack 

Description 
Notes 



iand 



iand = 84 (0x54) 

value Lwordl y value Lword2 9 value2.wordl, value2.word2 
result word 1, resultword2 

Both valuel and value2 must be of type int. They are popped from the operand stack. An 
int result is calculated by taking the bitwise AND (conjunction) of valuel and value2. The 
result is pushed onto the operand stack. 

If a virtual machine does not support the int data type, the iand instruction will not be 
available. 



130 Java Card Virtual Machine 2.1 Specification • January 29, 1999 



iastore 



Store into int array 



Format 

Forms 

Stack 

Description 



iastore 



iastore - 58 (0x3a) 

arrayref index, value.wordl, value.word2 : 



The arrayref must be of type reference and must refer to an array whose components are 
of type int. The index must be of type short and value must be of type int. The arrayref, 
index and value are popped from the operand stack. The int value is stored as the compo- 
nent of the array indexed by index. 

Runtime Exception 

If arrayref is null, sastore throws a NullPointerException. 

Otherwise, if index is not within the bounds of the array referenced by arrayref the sastore 
instruction throws an ArraylndexOutOfBoundsException. 



Notes 



If a virtual machine does not support the int data type, the iastore instruction will not be 
available. 
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icmp 

Format 

Forms 

Stack 

Description 



Notes 



Compare int 



icmp 



icmp = 95 (0x5f) 

valueLwordl, value Lword2, value2.wordl , value2.word2^> 
result 

Both value 1 and value2 must be of type int. They are both popped from the operand stack, 
and a signed integer comparison is performed, livaluel is greater than value2, the short 
value 1 is pushed onto the operand stack. If value! is equal to value2, the short value 0 is 
pushed onto the operand stack. If value I is less than value2, the short value -1 is pushed 
onto the operand stack. 

If a virtual machine does not support the int data type, the icmp instruction will not be 
available. 
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iconst_<i> 

Push int constant 



Format 
Forms 



Stack 

Description 
Notes 



icons t <i> 



icons t_ml = 10(0x09) 
iconstj) = 1 1 (Oxa) 
iconstj = 12 (Oxb) 
icons t_2 =13 (Oxc) 
iconstj = 14 (Oxd) 
[const 4- 15 (Oxe) 
iconstj = 16 (OxQ 



<i>.wordl, <i>.word2 



Push the int constant <i> (-/, 0, 7, 2, J, 4, or 5) onto the operand stack. 

If a virtual machine does not support the int data type, the iconst_<i> instruction will not 
be available. 
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idiv 



Divide int 

Format 

idiv 

Forms 

idiv = 72 (0x48) 

Stack 

valuel. wordl, valuel. word2, value2.wordl, value2.word2 => 
. . . , result word 1 , result. word2 

Description 

Both valuel and value2 must be of type int. The values are popped from the operand stack. 
The int result is the value of the Java expression valuel I value2. The result is pushed onto 
the operand stack. 

An int division rounds towards 0; that is, the quotient produced for int values in n/d is an 
int value q whose magnitude is as large as possible while satisfying | d • q \ = \ n \. More- 
over, q is a positive when | n | = | d | and n and d have the same sign, but q is negative when 
| n | = | d | and n and d have opposite signs. 

There is one special case that does not satisfy this rule: if the dividend is the negative inte- 
ger of the largest possible magnitude for the int type, and the divisor is then overflow 
occurs, and the result is equal to the dividend. Despite the overflow, no exception is thrown 
in this case. 

Runtime Exception 

If the value of the divisor in an int division is 0, idiv throws an ArithmeticException. 

Notes 

If a virtual machine does not support the int data type, the idiv instruction will not be avail- 
able. 
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if acmp<cond> 

Branch if reference comparison succeeds 



Format 



Forms 



Stack 



ifjicmp<cond> 
branch 



if_acmpeq= 104(0x68) 
ifjacmpne = 105 (0x69) 

valuel, valuel ^> 



Description 



Both valuel and valuel must be of type reference. They are both popped from the oper- 
and stack and compared. The results of the comparisons are as follows: 

• eq succeeds if and only if valuel = valuel 

• ne succeeds if and only if valuel ? value2 

If the comparison succeeds, branch is used as signed 8-bit offset, and execution proceeds at 
that offset from the address of the opcode of this if_acmp<cond> instruction. The target 
address must be that of an opcode of an instruction within the method that contains this 
if_acmp<cond> instruction. 

Otherwise, execution proceeds at the address of the instruction following this 
if_acmp<cond> instruction. 
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if_acmp<cond>_w 

Branch if reference comparison succeeds (wide index) 



Format 



Forms 



Stack 



if_acmp<cond>_w 
branchbytel 



branchbyte2 



ifjzcmpeqjv - 160 (OxaO) 
if_acmpne_w - 161 (Oxal) 

value I, value! => 



Description 



Both value! and value2 must be of type reference. They are both popped from the oper- 
and stack and compared. The results of the comparisons are as follows: 

• eq succeeds if and only if value I = value2 

• ne succeeds if and only if valuel ? value2 

If the comparison succeeds, the unsigned bytes branchbytel and branchbyte2 are used to 
construct a signed 16-bit branchoffset, where branchoffset is {branchbytel « 8) | 
branchbyte2. Execution proceeds at that offset from the address of the opcode of this 
if_acmp<cond>_w instruction. The target address must be that of an opcode of an instruc- 
tion within the method that contains this if_acmp<cond>_w instruction. 

Otherwise, execution proceeds at the address of the instruction following this 
ifjxcmp<cond>_w instruction. 
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i f _s cmp < c ond > 

Branch if short comparison succeeds 

Format a , 

if_scmp<cond> 
branch 

Forms 

if_scmpeq = 106 (0x6a) 
ifjcmpne = 107 (0x6b) 
if_scmplt= 108 (0x6c) 
ifjcmpge = 109 (0x6d) 
if_scmpgt = 110(0x6e) 
if_scmple= 111 (0x6f) 

Stack 

value 1, value2=> 

Description 

Both va/we/ and value2 must be of type short. They are both popped from the operand 
stack and compared. All comparisons are signed. The results of the comparisons are as fol- 
lows: 

• eq succeeds if and only if valuel = value2 

• ne succeeds if and only if valuel ? valuel 

• It succeeds if and only if valuel < value2 

• le succeeds if and only if valuel = value2 

• gt succeeds if and only if valuel > valuel 

• ge succeeds if and only if value I = value2 

If the comparison succeeds, branch is used as signed 8-bit offset, and execution proceeds at 
that offset from the address of the opcode of this if_scmp<cond> instruction. The target 
address must be that of an opcode of an instruction within the method that contains this 
if_scmp<cond> instruction. 

Otherwise, execution proceeds at the address of the instruction following this 
if_scmp<cond> instruction. 
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i f _scmp<cond>_w 



Format 



Forms 



Stack 



Branch if short comparison succeeds (wide index) 



if_scmp<cond>_w 



branchbytel 
branchbyte2 



if_scmpeq_w = 
ifscmpnew = 
if_scmplt_w = 
if_scmpge_w - 
if_scmpgt_w = 
if_scmple_w = 



162 (0xa2) 
= 163 (0xa3) 
164(0xa4) 
= 165 (0xa5) 

166 (0xa6) 

167 (0xa7) 



., valuel, value2: 



Description 



Both value! and value! must be of type short. They are both popped from the operand 
stack and compared. All comparisons are signed. The results of the comparisons are as fol- 
lows: 

• eq succeeds if and only if value I = value2 

• ne succeeds if and only if value I ? value2 

• // succeeds if and only if valuel < value2 

• le succeeds if and only if valuel = value2 

• gt succeeds if and only if valuel > value2 

• ge succeeds if and only if valuel = value2 

If the comparison succeeds, the unsigned bytes branchbytel and branchbyte2 are used to 
construct a signed 16-bit branchqffset, where branchoffset is {branchbytel « 8) | 
branchbyte2. Execution proceeds at that offset from the address of the opcode of this 
if_scmp<cond>_w instruction. The target address must be that of an opcode of an instruc- 
tion within the method that contains this if_scmp<cond> jw instruction. 

Otherwise, execution proceeds at the address of the instruction following this 
if_scmp<cond>_w instruction. 
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if <cond> 

Branch if short comparison with zero succeeds 

Format _ ^ 

if<cond> 
branch 

Forms 

ifeq = 96 (0x60) 
ifiie = 97(0x61) 
iflt = 9% (0x62) 
ifge = 99 (0x63) 
1/^= 100(0x64) 
/y7e= 101 (0x65) 

Stack 

valuer 

Description 

The value must be of type short. It is popped from the operand stack and compared against 
zero. All comparisons are signed. The results of the comparisons are as follows: 

• eq succeeds if and only if value = 0 

• ne succeeds if and only if value ? 0 

• // succeeds if and only if value < 0 

• le succeeds if and only if value = 0 

• gt succeeds if and only if value > 0 

• ge succeeds if and only if value = 0 

If the comparison succeeds, branch is used as signed 8-bit offset, and execution proceeds at 
that offset from the address of the opcode of this if<cond> instruction. The target address 
must be that of an opcode of an instruction within the method that contains this if<cond> 
instruction. 

Otherwise, execution proceeds at the address of the instruction following this if<cond> 
instruction. 



♦ 
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if<cond> w 



Format 



Forms 



Stack 



Branch if short comparison with zero succeeds (wide index) 



if<cond>_w 



branchbytel 



branchbyte2 



ifeq_w= 152 (0x98) 
ifrie_w= 153 (0x99) 
iflt_w= 154 (0x9a) 
ifge_w= 155 (0x9b) 
ifgtjv= 156 (Qx9c) 
ifle_w= 157 (0x9d) 

valuer 



Description 



The value must be of type short. It is popped from the operand stack and compared against 
zero. All comparisons are signed. The results of the comparisons are as follows: 

• eq succeeds if and only if value = 0 

• ne succeeds if and only if value ? 0 

• // succeeds if and only if value < 0 

• le succeeds if and only if value = 0 

• gt succeeds if and only if value > 0 

• ge succeeds if and only it value = 0 

If the comparison succeeds, the unsigned bytes branchbytel and branchbyte2 are used to 
construct a signed 16-bit branchqffset, where branchoffset is {branchbytel « 8) | 
branchbytel. Execution proceeds at that offset from the address of the opcode of this 
if<cond>_w instruction. The target address must be that of an opcode of an instruction 
within the method that contains this if<cond>_w instruction. 

Otherwise, execution proceeds at the address of the instruction following this if<cond>_w 
instruction. 
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ifnonnull 



Branch if reference not null 



Format 

Forms 
Stack 



ifnonnull 
branch 



ifnonnull = 103 (0x67) 
valuer 



Description 

The value must be of type reference. It is popped from the operand stack. If the value is 
not null, branch is used as signed 8-bit offset, and execution proceeds at that offset from 
the address of the opcode of this ifnonnull instruction. The target address must be that of an 
opcode of an instruction within the method that contains this ifnonnull instruction. 

Otherwise, execution proceeds at the address of the instruction following this ifnonnull 
instruction. 
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ifnonnull_w 

Branch if reference not null (wide index) 

Format 



Forms 
Stack 



ifhonnuii_w 
branchbytel 



branchbyte2 



ijhonnulljv = 159 (0x9f) 
value => 



Description 



The value must be of type reference. It is popped from the operand stack. If the value is 
not null, the unsigned bytes branchbytel and branchbyte2 are used to construct a signed 
16-bit branchoffset, where branchoffset is {branchbytel « 8) | branchbytel Execution 
proceeds at that offset from the address of the opcode of this ifnonnull w instruction. The 
target address must be that of an opcode of an instruction within the method that contains 
this ifnonnull_w instruction. 

Otherwise, execution proceeds at the address of the instruction following this ifnonnull w 
instruction. 
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if null 

Format 

Forms 
Stack 



Branch if reference is null 



ijmnr 



branch 



ifhull= 102 (0x66) 
valuer 



Description 

The value must be of type reference. It is popped from the operand stack. If the value is 
null, branch is used as signed 8-bit offset, and execution proceeds at that offset from the 
address of the opcode of this ijhull instruction. The target address must be that of an opcode 
of an instruction within the method that contains this ijhull instruction. 

Otherwise, execution proceeds at the address of the instruction following this ifnull instruc- 
tion. 
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ifnull_w 

Branch if reference is null (wide index) 

Format 



ijhull_w 
branchbytel 



branchbyte2 



Forms 

//««//_w=158(0x9e) 

Stack 

Description 

The value must be of type reference. It is popped from the operand stack. If the value is 
null, the unsigned bytes branchbytel and branchbytel are used to construct a signed 16- 
bit branchoffset, where branchoffset is {branchbytel « 8) | branchbyte2. Execution pro- 
ceeds at that offset from the address of the opcode of this ifnull_w instruction. The target 
address must be that of an opcode of an instruction within the method that contains this 
ifnull_w instruction. 

Otherwise, execution proceeds at the address of the instruction following this ifnull_w 
instruction. 
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iinc 



Increment local int variable by constant 



Format 

Forms 
Stack 

Description 



Notes 



line 



index 



const 



iinc = 90 (0x5a) 
No change 

The index is an unsigned byte. Both index and index + 1 must be valid indices into the local 
variables of the current frame. The local variables at index and index + 1 together must con- 
tain an int. The const is an immediate signed byte. The value const is first sign-extended to 
an int, then the int contained in the local variables at index and index + 1 is incremented 
by that amount. 

If a virtual machine does not support the int data type, the iinc instruction will not be avail- 
able. 
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line w 



Format 



Forms 
Stack 

Description 



Notes 



Increment local int variable by constant 



unc w 



irti 



dex 



byte! 



byte2 



iinc_w= 151 (0x97) 
No change 

The index is an unsigned byte. Both index and index + 1 must be valid indices into the local 
variables of the current frame. The local variables at index and index + 1 together must con- 
tain an int. The immediate unsigned byte I and byte2 values are assembled into an interme- 
diate short where the value of the short is {bytel « 8) | bytel. The intermediate value is 
then sign-extended to an int const. The int contained in the local variables at index and 
index + 1 is incremented by const 

If a virtual machine does not support the int data type, the iinc xv instruction will not be 
available. 



146 



Java Card Virtual Machin 2.1 Specification • January 29, 1999 



iipush 



Push int 



Format 



Forms 
Stack 

Description 
Notes 



iipush 
byte! 
byte2 
byte3 
byte4 



iipush = 20 (0x14) 



value L word 7, valuel.word2 

The immediate unsigned byte I, byte2, byte3, and byte4 values are assembled into a signed 
int where the value of the int is (bytel « 24) | {byte2 « 16) | (byte3 « 8) | byte4. The 
resulting value is pushed onto the operand stack. 

If a virtual machine does not support the int data type, the iipush instruction will not be 
available. 
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iload 



Load int from local variable 



Format 

Forms 
Stack 

Description 



Notes 



iload 



index 



iload =23 (0x17) 



valuel.wordl, valueJ.word2 

The index is an unsigned byte. Both index and index + 1 must be valid indices into the local 
variables of the current frame. The local variables at index and index + 1 together must con- 
tain an int. The value of the local variables at index and index + 1 is pushed onto the oper- 
and stack. 

If a virtual machine does not support the int data type, the iload instruction will not be 
available. 
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iload <n> 



Format 



Forms 



Stack 



Description 



Notes 



Load int from local variable 
iload <n> 



/7oa</_0 = 32(Ox2O) 
UoadJ = 32 (0x21) 
iload J = 34 (0x22) 
iload J = 35 (0x23) 



valuel.wordl, valuel.word2 

Both <n> and <n> + 1 must be a valid indices into the local variables of the current frame. 
The local variables at <n> and <n> + 1 together must contain an int. The value of the 
local variables at <n> and <n> + 1 is pushed onto the operand stack. 

Each of the iload_<n> instructions is the same as iload with an index of <n>, except that 
the operand <n> is implicit. 

If a virtual machine does not support the int data type, the iload_<n> instruction will not 
be available. 
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i lookup switch 

Access jump table by key match and jump 



Format 



Pair Format 



Forms 
Stack 



ilookupswitch 
defaultbytel 



defaultbyte2 



npairsl 



npairs2 



match-offset pairs. . . 



matchbytel 



matchbyte2 



matchbytel 
matchbyte4 



offsetbytel 



offsetbyte2 



ilookupsmtch = 118 (0x76) 
. .., key.wordl, key.word2 



Description 



Notes 



An ilookupswitch instruction is a variable-length instruction. Immediately after the ilook- 
upswitch opcode follow a signed 16-bit value default, an unsigned 16-bit value npairs, and 
then npairs pairs. Each pair consists of an int match and a signed 16-bit offset. Each match 
is constructed from four unsigned bytes as (matchbytel « 24) | (matchbyte2 « 16) | 
(matchbytel « 8) | matchbyte4. Each offset is constructed from two unsigned bytes as 
(offsetbytel « 8) | offsetbyte2. 

The table match-offset pairs of the ilookupswitch instruction must be sorted in increasing 
numerical order by match. 

The key must be of type int and is popped from the operand stack and compared against 
the match values. If it is equal to one of them, then a target address is calculated by adding 
the corresponding offset to the address of the opcode of this ilookupswitch instruction. If the 
key does not match any of the match values, the target address is calculated by adding 
default to the address of the opcode of this ilookupswitch instruction. Execution then contin- 
ues at the target address. 

The target address that can be calculated from the offset of each match-offset pair, as well as 
the one calculated from default, must be the address of an opcode of an instruction within 
the method that contains this ilookupswitch instruction. 

The match-offset pairs are sorted to support lookup routines that are quicker than linear 
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search. 

If a virtual machine does not support the int data type, the ilookupswitch instruction will 
not be available. 
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imul 



Multiply int 



Format 

Forms 

Stack 

Description 



Notes 



imul 



imul = 70 (0x46) 

. . ., valuel. wordl, valuel. word2, value2.wordl, value2.word2 =s> 
. . . , result, wordl, result.word2 

Both valuel and value2 must be of type int. The values are popped from the operand stack. 
The int result is valuel * value2. The result is pushed onto the operand stack. 

If an imul instruction overflows, then the result is the low-order bits of the mathematical 
product as an int. If overflow occurs, then the sign of the result may not be the same as the 
sign of the mathematical product of the two values. 

If a virtual machine does not support the int data type, the imul instruction will not be 
available. 
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ineg 

Format 

Forms 

Stack 

Description 



Notes 



Negate int 



meg 



ineg = 76 (0x4c) 

value.wordl , value.word2 => 
resultwordl, result.word2 

The value must be of type int. It is popped from the operand stack. The int result is the 
arithmetic negation of value, -value. The result is pushed onto the operand stack. 

For int values, negation is the same as subtraction from zero. Because the Java Card Vir- 
tual Machine uses two's-complement representation for integers and the range of two's- 
complement values is not symmetric, the negation of the maximum negative int results in 
that same maximum negative number. Despite the fact that overflow has occurred, no 
exception is thrown. 

For all int values x, -x equals (~x) + 1. 

If a virtual machine does not support the int data type, the imul instruction will not be 
available. 
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instanceof 

Determine if object is of given type 

Format 

instanceof 

atype 
indexbytel 
indexbyte2 

Forms 

instanceof = 149 (0x95) 

Stack 

objectref*=> 
. . . , result 

Description 

The unsigned byte atype is a code that indicates if the type against which the object is being 
checked is an array type or a class type. It must take one of the following values or zero: 



Array Type 


atype 


T_BOOLEAN 


10 


T_BYTE 


11 


T_SHORT 


12" 


T_INT 


13 


T_REFERENCE 


14 



If the value of atype is 10, 1 1, 12, or 13, the values of the indexbytel and indexbyte2 must 
be zero, and the value of atype indicates the array type against which to check the object. 
Otherwise the unsigned indexbytel and indexbyte2 are used to construct an index into the 
constant pool of the current package, where the value of the index is {indexbytel « 8) | 
indexbytel The item at that index in the constant pool must be of type 
CONSTANT Classref , a reference to a class or interface type. The reference is resolved. If 
the value of atype is 14, the object is checked against an array type which is an array of 
object references of the type of the resolved class. If the value of atype is zero, the object is 
checked against a class or interface type which is the resolved class. 

The objectref must be of type reference. It is popped from the operand stack, liobjectref 
is not null and is an instance of the resolved class, array or interface, the instanceof 
instruction pushes a short result of 1 on the operand stack. Otherwise it pushes a short 
result of 0. 

The following rules are used to determine whether an objectref that is not null is an 
instance of the resolved type: if S is the class of the object referred to by objectref 'and t is 
the resolved class, array or interface type, instanceof determines whether objectref is an 
instance of r as follows: 

n If S is an ordinary (non-array) class, then: 

a If r is a class type, then S must be the same class as T, or a subclass of T. 
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a If T is an interface type, S must implement interface T. 

n If S is a class representing the array type SC[ ] , that is, an array of components of type 
SC, then: 

o If T is a class type, then T must be Object. 

n If T is an array type TC[ ) , that is, an array of components of type TC, then one of the 
following must be true: 

a TC and type SC are the same primitive type. 

n TC and SC are reference types, and type SC can be cast to TC by these runtime 
rules. 

s cannot be an interface type, because there are no instances of interfaces, only instances of 
classes and arrays. 

Notes 

The instanceof instruction is fundamentally very similar to the checkcast instruction. It dif- 
fers in its treatment of null, its behavior when its test fails {checkcast throws an exception, 
instanceof pushes a result code), and its effect on the operand stack. 

If a virtual machine does not support the int data type, the value of atype may not be 13 
(array type = T_INT). 
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invokeinterf ace 

Invoke interface method 

Format 



Forms 
Stack 



invokeinterface 



nargs 



indexbytel 



indexbyte2 
method 



invokeinterface = 142 (0x8e) 
. . ., objectref [argl, [arg2 ...]]: 



Description 

The unsigned indexbytel and indexbyte2 are used to construct an index into the constant 
pool of the current package, where the value of the index is (indexbytel « 8) | indexbyte2. 
The constant pool item at that index must be of type CONSTANT_Class ref , a reference to 
an interface class. The specified method is resolved. The interface method must not be 
<init>, an instance initialization method, or <clinit>, a class or interface initialization 
method. 

The nargs operand is an unsigned byte which must not be zero. The method operand is an 
unsigned byte which is the interface method token for the method to be invoked. The 
objectref must be of type reference and must be followed on the operand stack by nargs 
- 1 words of arguments. The number of words of arguments and the type and order of the 
values they represent must be consistent with those of the selected interface method. 

The interface table of the class of the type of objectref is determined. If objectref is an array 
type, then the interface table of class Object is used. The interface table is searched for the 
resolved interface. The result of the search is a table which is used to map the method token 
to a index. 

The index is an unsigned byte which is used as an index into the method table of the class of 
the type of objectref If the objectref is an array type, then the method table of class Ob j ect 
is used. The table entry at that index includes a direct reference to the method's code and 
modifier information. 

The nargs - 1 words of arguments and objectref are popped from the operand stack. A new 
stack frame is created for the method being invoked, and objectref and the arguments are 
made the values of its first nargs words of local variables, with argl in local variable at 
index 0, argl in local variable at offset 2, arg2 immediately following that, and so on. The 
new stack frame is then made current, and the Java Card Virtual Machine pc is set to the 
opcode of the first instruction of the method to be invoked. Execution continues with the 
first instruction of the method. 
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Runtime Exception 

If objectref is null, the invokeinterface instruction throws a NullPointerException. 
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invokespecial 

Invoke instance method; special handling for superclass, private, and instance initialization 
method invocations 

Format 

invokespecial 
indexbytel 
indexbyte2 



invokespecial ~ 140 (0x8c) 

. . ., objectref [argl, [arg2 ...]]=> 



The unsigned indexbytel and indexbyte2 are used to construct an index into the constant 
pool of the current package, where the value of the index is {indexbytel « 8) | indexbytel. 
The constant pool item at that index must be of type CONSTANT_StaticMethodref , a ref- 
erence to a statically linked instance method, or of type CONSTANTSuperMethodref , a 
reference to an instance method of a specified class. The reference is resolved. The resolved 
method must not be <clinit>, a class or interface initialization method. If the method is 
<init>, an instance initialization method, then the method must only be invoked once on 
an uninitialized object, and before the first backward branch following the execution of the 
new instruction that allocated the object. Finally, if the method is protected, then it must 
be either a member of the current class or a member of a superclass of the current class, and 
the class of objectref must be either the current class or a subclass of the current class. 

The resolved method includes the code for the method, an unsigned byte nargs that must 
not be zero, and the method's modifier information. 

The objectref must be of type reference, and must be followed on the operand stack by 
nargs - 1 words of arguments, where the number of words of arguments and the type and 
order of the values they represent must be consistent with those of the selected instance 
method. 

The nargs - 1 words of arguments and objectref are popped from the operand stack. A new 
stack frame is created for the method being invoked, and objectref and the arguments are 
made the values of its first nargs words of local variables, with objectref 'in local variable 0, 
argl in local variable 1, and so on. The new stack frame is then made current, and the Java 
Card Virtual Machine pc is set to the opcode of the first instruction of the method to be 
invoked. Execution continues with the first instruction of the method. 

Runtime Exception 

If objectref is null, the invokespecial instruction throws a NullPointerException. 



Forms 
Stack 



Description 
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invokestatic 

Invoke a class (static) method 

Format 



Forms 
Stack 



invokestatic 
indexbytel 



indexbyte2 



invokestatic =141 (0x8d) 
...,[<*rgl,[arg2...]]^ 



Description 



The unsigned indexbytel and indexbytel are used to construct an index into the constant 
pool of the current package, where the value of the index is (indexbytel « 8) | indexbyte2. 
The constant pool item at that index must be of type CONSTANT_StaticMethodref, a ref- 
erence to a static method. The method must not be <init>, an instance initialization 
method, or <clinit>, a class or interface initialization method. It must be static, and 
therefore cannot be abstract. Finally, if the method is protected, then it must be either 
a member of the current class or a member of a superclass of the current class. 

The resolved method includes the code for the method, an unsigned byte nargs that may be 
zero, and the method's modifier information. 

The operand stack must contain nargs words of arguments, where the number of words, of 
arguments and the type and order of the values they represent must be consistent with those 
of the resolved method . 

The nargs words of arguments are popped from the operand stack. A new stack frame is 
created for the method being invoked, and the words of arguments are made the values of its 
first nargs words of local variables, with argl in local variable 0, arg2 in local variable 7, 
and so on. The new stack frame is then made current, and the Java Card Virtual Machine pc 
is set to the opcode of the first instruction of the method to be invoked. Execution continues 
with the first instruction of the method. 
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invokevirtual 

Invoke instance method; dispatch based on class 

Format 



Forms 
Stack 



invokevirtual 
indexbytel 



indexbytel 



invokevirtual = 139 (0x8b) 
objectref [argl, [arg2 ...]]: 



Description 

The unsigned indexbytel and indexbyte2 are used to construct an index into the constant 
pool of the current package, where the value of the index is {indexbytel « 8) | indexbytel. 
The constant pool item at that index must be of type CONSTANT_virtualMethodref , a 
reference to a class and a virtual method token. The specified method is resolved. The 
method must not be <init>, an instance initialization method, or <clinit>, a class or 
interface initialization method. If the method is protected, then it must be either a mem- 
ber of the current class or a member of a superclass of the current class, and the class of 
objectref must be either the current class or a subclass of the current class. 

The resolved method reference includes an unsigned index into the method table of the 
resolved class and an unsigned byte nargs that must not be zero. 

The objectref must be of type reference. The index is an unsigned byte which is used as 
an index into the method table of the class of the type of objectref. If the objectref is an 
array type, then the method table of class Ob j ect is used. The table entry at that index 
includes a direct reference to the method's code and modifier information. 

The objectref must be followed on the operand stack by nargs - 1 words of arguments, 
where the number of words of arguments and the type and order of the values they represent 
must be consistent with those of the selected instance method. 

The nargs - 1 words of arguments and objectref are popped from the operand stack. A new 
stack frame is created for the method being invoked, and objectref and the arguments are 
made the values of its first nargs words of local variables, with objectref in local variable 0, 
argl in local variable 7, and so on. The new stack frame is then made current, and the Java 
Card Virtual Machine pc is set to the opcode of the first instruction of the method to be 
invoked. Execution continues with the first instruction of the method. 

Runtime Exception 

If objectref is null, the invokevirtual instruction throws a NullPointerException. 
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ior 



Boolean OR int 



Format 

Forms 

Stack 

Description 
Notes 



ior 



K>r = 86(0x56) 

value 1. word I, value !.word2, value2.wordl, value2.word2 => 
result, word I > result.word2 

Both value! and value2 must be of type int. The values are popped from the operand stack. 
An int result is calculated by taking the bitwise inclusive OR of value! and value2. The 
result is pushed onto the operand stack. 

If a virtual machine does not support the int data type, the ior instruction will not be avail- 
able. 
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irem 



Remainder int 



irem 



Format 
Forms 

irem = 74 (0x4a) 

Stack 

valueLwordl, value l.word2, value2.wordl, value2.word2^> 
result.wordl, result.word2 

Description 

Both valuel and value2 must be of type int. The values are popped from the operand stack. 
The int result is the value of the Java expression valuel - (valuel I valuel) * value2. The 
result is pushed onto the operand stack. 

The result of the irem instruction is such that (a/bj *b + (a%b) is equal to a. This iden- 
tity holds even in the special case that the dividend is the negative int of largest possible 
magnitude for its type and the divisor is -1 (the remainder is 0). It follows from this rule 
that the result of the remainder operation can be negative only if the dividend is negative 
and can be positive only if the dividend is positive. Moreover, the magnitude of the result is 
always less than the magnitude of the divisor. 

Runtime Exception 

If the value of the divisor for a short remainder operator is 0, irem throws an Arithmet- 
icException. 



Notes 



If a virtual machine does not support the int data type, the irem instruction will not be 
available. 
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ireturn 

Format 

Forms 

Stack 

Description 
Notes 



Return int from method 



ireturn 



ireturn = 121 (0x79) 



value.word], value.word2 => 
[empty] 

The value must be of type int . It is popped from the operand stack of the current frame and 
pushed onto the operand stack of the frame of the invoker. Any other values on the operand 
stack of the current method are discarded. 

The virtual machine then reinstates the frame of the invoker and returns control to the 
invoker. 

If a virtual machine does not support the int data type, the ireturn instruction will not be 
available. 
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ishl 



Shift left int 

Format 

ishl 

Forms 

ishl = IS (0x4e) 

Stack 

value 1. word I, value Lword2, value2.wordl, value2.word2 -=> 
result.wordl, result.word2 

Description 

Both valuel and value2 must be of type int. The values are popped from the operand stack. 
An int result is calculated by shifting valuel left by s bit positions, where s is the value of 
the low five bits of value2. The result is pushed onto the operand stack. 

Notes 

This is equivalent (even if overflow occurs) to multiplication by 2 to the power s . The shift 
distance actually used is always in the range 0 to 31, inclusive, as if value2 were subjected 
to a bitwise logical AND with the mask value Ox If. 

If a virtual machine does not support the int data type, the ishl instruction will not be avail- 
able. 
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ishr 



Arithmetic shift right int 



Format 

Forms 

Stack 

Description 



Notes 



Notes 



ishr 



ishr = 80 (0x50) 

valueLwordl, valuel. word2 t value2.wordl , value2.word2^> 
result.wordl, result.word2 

Both value! and value2 must be of type int. The values are popped from the operand stack. 
An int result is calculated by shifting valuel right by s bit positions, with sign extension, 
where s is the value of the low five bits of value2. The result is pushed onto the operand 
stack. 

The resulting value is [.(valuel) f Is J, where s is value2 & Oxlf. For nonnegative valuel, 
this is equivalent (even if overflow occurs) to truncating int division by 2 to the power s. 
The shift distance actually used is always in the range 0 to 31, inclusive, as if value2 were 
subjected to a bitwise logical AND with the mask value Oxlf. 

If a virtual machine does not support the int data type, the ishr instruction will not be 
available. 
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istore 



Format 

Forms 
Stack 

Description 
Notes 



Store int into local variable 



istore 
index 



istore = 42 (0x2a) 

value.wordl, va!ue.word2 => 



The index is an unsigned byte. Both index and index + 1 must be a valid index into the local 
variables of the current frame. The value on top of the operand stack must be of type int. It 
is popped from the operand stack, and the local variables at index and index + 1 are set to 
value. 



If a virtual machine does not support the int data type, the istore instruction will not be 
available. 
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is tore 

Format 
Forms 

Stack 

Description 
Notes 



<n> 

Store int into local variable 



is tore <n> 



51 (0x33) 

52 (0x34) 

53 (0x35) 

54 (0x36) 

value.wordl, value.word2 => 



Both <n> and <n> + 1 must be a valid indices into the local variables of the current frame. 
The value on top of the operand stack must be of type int. It is popped from the operand 
stack, and the local variables at index and index + 1 are set to value. 

If a virtual machine does not support the int data type, the istore_<n> instruction will not 
be available. 



istorej) - 
is tore _1 ~ 
is tore _2 = 
istore 3 = 



Chapter 7 Java Card Virtual Machine Instruction Set 167 



isub 



Subtract int 



Format 

Forms 

Stack 

Description 



Notes 



isub 



isub = 68 (0x44) 

value I. word 7, valueI.word2, value2.wordI, value2.word2 => 
result word I, result word2 

Both value 1 and value2 must be of type int. The values are popped from the operand stack. 
The int result is valuel - value2. The result is pushed onto the operand stack. 

For int subtraction, a - b produces the same result as a + (-b) . For int values, subtrac- 
tion from zeros is the same as negation. 

Despite the fact that overflow or underflow may occur, in which case the result may have a 
different sign than the true mathematical result, execution of an isub instruction never 
throws a runtime exception. 

If a virtual machine does not support the int data type, the isub instruction will not be 
available. 
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itableswitch 

Access jump table by int index and jump 

Format ^ 

itableswitch 
defaultbytel 
defaultbyte2 

lowbytel 

lowbyte2 

lowbyte3 

lowbyte4 

highbytel 

highbyte2 

highbyte3 

highbyte4 
jump offsets... 

Offset Format 

offsetbytel 
offsetbyte2 

Forms 

itableswitch =116 (0x74) 

Stack 

index o 

Description 

An itableswitch instruction is a variable-length instruction. Immediately after the ita- 
bleswitch opcode follow a signed 16-bit value default, a signed 32-bit value low, a signed 
32-bit value high, and then high - low + 1 further signed 16-bit offsets. The value low must 
be less than or equal to high. The high - low + 1 signed 16-bit offsets are treated as a 0- 
based jump table. Each of the signed 16-bit values is constructed from two unsigned bytes 
as (byte! « 8) | byte2. Each of the signed 32-bit values is constructed from four unsigned 
bytes as (byte I « 24) | (byte2 « 16) | (byte3 « 8) | byte4. 

The index must be of type int and is popped from the stack. If index is less than low or 
index is greater than high, then a target address is calculated by adding default to the 
address of the opcode of this itableswitch instruction. Otherwise, the offset at position index 
- low of the jump table is extracted. The target address is calculated by adding that offset to 
the address of the opcode of this itableswitch instruction. Execution then continues at the 
target address. 

The target addresses which can be calculated from each jump table offset, as well as the one 
calculated from default, must be the address of an opcode of an instruction within the 
method that contains this itableswitch instruction. 
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Notes 

If a virtual machine does not support the int data type, the itableswitch instruction will not 
be available. 
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iushr 

Format 

Forms 

Stack 

Description 
Notes 



Logical shift right int 

iushr 

iushr = 82 (0x52) 

value I. word V, valuel. word2 y value2.wordl , value2.word2 => 
result.wordl, result.word2 



Both value 1 and vglue2 must be of type int. The values are popped from the operand stack. 
An int result is calculated by shifting the result right by s bit positions, with zero exten- 
sion, where s is the value of the low five bits of value2. The result is pushed onto the oper- 
and stack. 

If value! is positive and s is value2 & Ox 1 f, the result is the same as that of value 1 » s; if 
valuel is negative, the result is equal to the value of the expression (valuel » s) + (2 « 
~s). The addition of the (2 « ~s) term cancels out the propagated sign bit. The shift dis- 
tance actually used is always in the range 0 to 3 1 , inclusive, as if value2 were subjected to a 
bitwise logical AND with the mask value Ox If. 

If a virtual machine does not support the int data type, the iushr instruction will not be 
available. 
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ixor 



Boolean XOR int 



Format 

Forms 

Stack 

Description 
Notes 



ixor 



ixor = 88 (0x58) 

valuel.wordl, value l.word2, value2.wordl> value2.word2 => 
result.wordl, result.word2 

Both value! and value2 must be of type int. The values are popped from the operand stack. 
An int result is calculated by taking the bitwise exclusive OR of valuel and value2. The 
result is pushed onto the operand stack. 

If a virtual machine does not support the int data type, the ixor instruction will not be 
available. 
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jsr 

Jump subroutine 

Format 

branchbytel 
branchbyte2 

Forms 

>r= 113 (0x71) 

Stack 

... => 
address 

Description 

The address of the opcode of the instruction immediately following this jsr instruction is 
pushed onto the operand stack as a value of type returnAddress. The unsigned 
branchbytel and branchbyte2 are used to construct a signed 16-bit offset, where the offset 
is {branchbytel « 8) | branchbyte2. Execution proceeds at that offset from the address of 
this jsr instruction. The target address must be that of an opcode of an instruction within the 
method that contains this jsr instruction. 

Notes 

The jsr instruction is used with the ret instruction in the implementation of the finally 
clause of the Java language. Note that jsr pushes the address onto the stack and ret gets it 
out of a local variable. This asymmetry is intentional. 
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new 



Create new object 

Format 

new 
indexbytel 
indexbyte2 

Forms 

new = 143 (0x8f) 

Stack 

... => 

objectref 

Description 

The unsigned indexbytel and indexbyte2 are used to construct an index into the constant 
pool of the current package, where the value of the index is (indexbytel « 8) | indexbytel 
The item at that index in the constant pool must be of type CONSTANT Clas s re f , a refer- 
ence to a class or interface type. The reference is resolved and must result in a class type (it 
must not result in an interface type). Memory for a new instance of that class is allocated 
from the heap, and the instance variables of the new object are initialized to their default ini- 
tial values. The objectref, a reference to the instance, is pushed onto the operand stack. 

Notes 

The new instruction does not completely create a new instance; instance creation is not 
completed until an instance initialization method has been invoked on the uninitialized 
instance. 
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newarray 



Create new array 



Format 



Forms 



Stack 



Description 



newarray 



atype 



newarray = 144 (0x90) 

count => 
array ref 

The count must be of type short. It is popped off the operand stack. The count represents 
the number of elements in the array to be created. 

The unsigned byte atype is a code that indicates the type of array to create. It must take one 
of the following values: 



Array Type 


atype 


T_BOOLEAN 


10 


T_BYTE 


11 


T_SHORT 


12 


T_INT 


13 



A new array whose components are of type atype, of length count, is allocated from the 
heap. A reference arrayref to this new array object is pushed onto the operand stack. All 
of the elements of the new array are initialized to the default initial value for its type. 

Runtime Exception 

If count is less than zero, the newarray instruction throws a Negat ive Arrays izeExcep- 
tion. 



Notes 



If a virtual machine does not support the int data type, the value of atype may not be 13 
(array type = t_int). 
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nop 

Do nothing 

Format 

nop 



Forms 

nop = 0 (0x0) 

Stack 

No change 

Description 

Do nothing. 
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pop 

Format 

Forms 

Stack 

Description 
Notes 



Pop top operand stack word 



pop 



pop = 59(0x3b) 
word => 

The top word is popped from the operand stack. 

The pop instruction operates on an untyped word, ignoring the type of data it contains. 
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pop2 

Pop top two operand stack words 

Format 



pop2 



Forms 

pop2 = 60 (0x3c) 

Stack 

word2, word I 



Description 



Notes 



The top two words are popped from the operand stack. 

The pop2 instruction must not be used unless each of wordl and word2 is a word that con- 
tains a 16-bit data type or both together are the two words of a single 32-bit datum. 

Except for restrictions preserving the integrity of 32-bit data types, the pop2 instruction 
operates on an untyped word, ignoring the type of data it contains. 
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putf ield_<t> 

Set field in object 

Format 



Forms 



Stack 



putfield_<t> 
index 



pufield_a = 135 (0x87) 
putfield_b = 136 (0x88) 
putfield_s = 137 (0x89) 
putfield_i = 138 (0x8a) 

. . ., objectref, value => 



OR 

objectref, value.wordJ, value.word2 • 



Description 

The unsigned index is used as an index into the constant pool of the current package. The 
constant pool item at the index must be of type CONSTANT_lnstanceFieldref , a refer- 
ence to a class and a field token. If the field is protected, then it must be either a member 
of the current class or a member of a superclass of the current class, and the class of objec- 
tref must be either the current class or a subclass of the current class. 

The item must resolve to a field with a type that matches t, as follows: 

• a field must be of type reference 

• b field must be of type byte or type boolean 

• s field must be of type short 

• i field must be of type int 

The width of a field in a class instance is determined by the field type specified in the 
instruction. The item is resolved, determining the field offset. The objectref, which must be 
of type reference, and the value are popped from the operand stack. If the field is of type 
byte or type boolean, the value is truncated to a byte. The field at the offset from the 
start of the object referenced by objectref is set to the value. 

Runtime Exception 

If objectref is null, the putfield_<t> instruction throws a NullPointerException. 



Notes 



If a virtual machine does not support the int data type, the putfieldj instruction will not be 
available. 
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putf ield_<t>_this 

Set field in current object 

Format 

putfield_<t>jhis 
index 



Forms 

putfield_ajhis =181 (0xb5) 
putfieldjbjhis = 182 (0xb6) 
putfieldjjhis = 183 (0xb7) 
putfieldjjhis = 184 (0xb8) 



Stack 

....value => 
OR 

value.wordl, value.word2 => 

Description 

The currently executing method must be an instance method which was invoked using the 
invokevirtual, invokeinterface or invokespecial instruction. The local variable at index 0 
must contain a reference objectref to the currently executing method's this parameter. 
The unsigned index is used as an index into the constant pool of the current package. The 
constant pool item at the index must be of type CONSTANT_lnstanceFieldref , a refer- 
ence to a class and a field token. If the field is protected, then it must be either a member 
of the current class or a member of a superclass of the current class, and the class ofobjec- 
tref must be either the current class or a subclass of the current class. 

The item must resolve to a field with a type that matches t, as follows: 

• a field must be of type reference 

• b field must be of type byte or type boolean 

• s field must be of type short 

• i field must be of type int 

The width of a field in a class instance is determined by the field type specified in the 
instruction. The item is resolved, detennining the field offset. The value is popped from the 
operand stack. If the field is of type byte or type boolean, the value is truncated to a 
byte. The field at the offset from the start of the object referenced by objectref "is set to the 
value. 

Runtime Exception 

If objectref is null, the putfield_<t> jhis instruction throws a NullPointerException. 

Notes 

If a virtual machine does not support the int data type, the putfieldjjhis instruction will 
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not be available. 
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putf ield_<t>_w 

Set field in object (wide index) 

Format 

putfield<t>_w 
indexbytel 
indexbyte2 

Forms 

putfield_a_w = 177 (Oxbl) 
pufield_b_w = 178 (0xb2) 
putfieldj>__w = 179 (0xb3) 
pu field J_w = 180 (0xb4) 



Stack 

. . . , objectref value => 



OR 

objectref value.wordl, value.word2 ^> 



Description 

The unsigned indexbytel and indexbyte2 are used to construct an index into the constant 
pool of the current package, where the value of the index is {indexbytel « 8) | indexbyte2. 
The constant pool item at the index must be of type CONSTANT_lnstanceFieldref , a ref- 
erence to a class and a field token. If the field is protected, then it must be either a mem- 
ber of the current class or a member of a superclass of the current class, and the class of 
objectref must be either the current class or a subclass of the current class. 

The item must resolve to a field with a type that matches f, as follows: 

• a field must be of type reference 

• b field must be of type byte or type boolean 

• s field must be of type short 

• / field must be of type int 

The width of a field in a class instance is determined by the field type specified in the 
instruction. The item is resolved, determining the field offset. The objectref, which must be 
of type reference, and the value are popped from the operand stack. If the field is of type 
byte or type boolean, the value is truncated to a byte. The field at the offset from the 
start of the object referenced by objectref is set to the value. 

Runtime Exception 

If objectref is null, the putfield_<t>_w instruction throws a NullPointerException. 

Notes 

If a virtual machine does not support the int data type, the putfieldj_w instruction will not 
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be available. 
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putstatic <t> 

Set static field in class 

Format 



Forms 



putstatic_<t> 
indexbytei 



indexbytei 



putstaticja = 127 (0x7f) 
putstaticj* = 128 (0x80) 
putstatic_s = 129 (0x81) 
putstaticj = 130 (0x82) 



Stack 



. , value - 



OR 

value.wordJ , value.word2 ■ 



Description 



Notes 



The unsigned indexbytei and indexbyte2 are used to construct an index into the constant 
pool of the current package, where the value of the index is {indexbytei « 8) | indexbytei. 
The constant pool item at the index must be of type C0NSTANT_StaticFieldref , a refer- 
ence to a static field. If the field is protected, then it must be either a member of the cur- 
rent class or a member of a superclass of the current class. 

The item must resolve to a field with a type that matches f, as follows: 

• a field must be of type reference 

• b field must be of type byte or type boolean 

• s field must be of type short 

• i field must be of type int 

The width of a class field is determined by the field type specified in the instruction. The 
item is resolved, determining the class field. The value is popped from the operand stack. If 
the field is of type byte or type boolean, the value is truncated to a byte. The field is set 
to the value. 

If a virtual machine does not support the int data type, the putstatic instruction will not be 
available. 
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ret 



Return from subroutine 



Format 

Forms 
Stack 

Description 



Notes 



ret 



in 



dex 



ret = 114 (0x72) 
No change 

The index is an unsigned byte that must be a valid index into the local variables of the cur- 
rent frame. The local variable at index must contain a value of type returnAddress. The 
contents of the local variable are written into the Java Card Virtual Machine's pc register, 
and execution continues there. 

The ret instruction is used with the jsr instruction in the implementation of the finally 
keyword of the Java language. Note that jsr pushes the address onto the stack and ret gets it 
out of a local variable. This asymmetry is intentional. 

The ret instruction should not be confused with the return instruction. A return instruction 
returns control from a Java method to its invoker, without passing any value back to the 
invoker. 
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return 



Return void from method 



Format 

Forms 

Stack 

Description 



return 



return = 122 (0x7a) 



[empty] 



Any values on the operand stack of the current method are discarded. The virtual machine 
then reinstates the frame of the invoker and returns control to the invoker. 
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s2b 



Convert short to byte 



Format 

Forms 

Stack 

Description 
Notes 



~s7F 



s2b = 91 (0x5b) 

value => 
result 

The value on top of the operand stack must be of type short. It is popped from the top of 
the operand stack, truncated to a byte result, then sign-extended to a short result. The 
result is pushed onto the operand stack. 

The s2b instruction performs a narrowing primitive conversion. It may lose information 
about the overall magnitude of value. The result may also not have the same sign as value. 
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s2i 



Convert short to int 



Format 

Forms 

Stack 

Description 
Notes 



s2i 



s2i = 92 (0x5c) 

value => 
. . . , result word 1 , result. word2 

The value on top of the operand stack must be of type short. It is popped from the operand 
stack and sign-extended to an int result. The result is pushed onto the operand stack. 

The s2i instruction performs a widening primitive conversion. Because all values of type 
short are exactly representable by type int, the conversion is exact. 

If a virtual machine does not support the int data type, the s2i instruction will not be avail- 
able. 
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sadd 



Add short 



Format 

Forms 

Stack 

Description 



sadd 



sadd =65 (0x41) 

value!, value2=> 
result 

Both value! and value2 must be of type short. The values are popped from the operand 
stack. The short result is value! + value2. The result is pushed onto the operand stack. 

If a sadd instruction overflows, then the result is the low-order bits of the true mathematical 
result in a sufficiently wide two's-complement format. If overflow occurs, then the sign of 
the result may not be the same as the sign of the mathematical sum of the two values. 
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saload 



Load short from array 

Format 

saload 

Forms 

saload = 38 (0x46) 

Stack 

. . . , arrayref index => 
value 

Description 

The arrayref must be of type reference and must refer to an array whose components are 
of type short. The index must be of type short. Both arrayref and index are popped from 
the operand stack. The short value in the component of the array at index is retrieved and 
pushed onto the top of the operand stack. 

Runtime Exceptions 

If arrayref is null, saload throws a NullPointerException. 

Otherwise, if index is not within the bounds of the array referenced by arrayref the saload 
instruction throws an ArraylndexOutOf BoundsException. 
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sand 



Boolean AND short 

Format 

sand 

Forms 

sand = 83 (0x53) 

Stack 

value 1, value2^> 
result 

Description 

Both valuel and value2 are popped from the operand stack. A short result is calculated by 
taking the bitwise AND (conjunction) of valuel and valuel. The result is pushed onto the 
operand stack. 
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sastore 



Store into short array 



Format 

Forms 

Stack 



sastore 



sastore = 57 (0x39) 



.., arrayref index, value : 



Description 

The arrayref must be of type reference and must refer to an array whose components are 
of type short. The index and value must both be of type short. The arrayref, index and 
value are popped from the operand stack. The short value is stored as the component of 
the array indexed by index. 

Runtime Exception 

If arrayref is null, sastore throws a NullPointerException. 

Otherwise, if index is not within the bounds of the array referenced by arrayref, the sastore 
instruction throws an ArraylndexOutOf BoundsException. 
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sconst <s> 



Push short constant 

Format 

sconst_<s> 

Forms 

sconst _m I =2 (0x2) 
sconst J) = 3 (0x3) 
sconst Jt = 4 (0x4) 
sconst ! = 5 (0x5) 
sconst 3 = 6 (0x6) 
sconst _4= 7 (0x7) 
sconst J = 8 (0x8) 

Stack 

... => 

Description 

Push the short constant <s> (-1,0, 1, 2,3, 4, or 5) onto the operand stack. 
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sdiv 



Divide short 

Format 

sdiv 

Forms 

sdiv = 71 (0x47) 

Stack 

value!, value! 
result 

Description 

Both value! and value! must be of type short. The values are popped from the operand 
stack. The short result is the value of the Java expression value! I value!. The result is 
pushed onto the operand stack. 

A short division rounds towards 0; that is, the quotient produced for short values in n/d 
is a short value q whose magnitude is as large as possible while satisfying | d - q | = | n |. 
Moreover, q is a positive when | n \ - | d \ and n and d have the same sign, but q is negative 
when | n \ = \ d | and n and d have opposite signs. 

There is one special case that does not satisfy this rule: if the dividend is the negative inte- 
ger of the largest possible magnitude for the short type, and the divisor is -7, then over- 
flow occurs, and the result is equal to the dividend. Despite the overflow, no exception is 
thrown in this case. 

Runtime Exception 

If the value of the divisor in a short division is 0, sdiv throws an Ar ithmeticException. 
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sine 

Format 

Forms 
Stack 

Description 



Increment local short variable by constant 



sine 



index 



const 



sine = 89 (0x59) 



No change 



The index is an unsigned byte that must be a valid index into the local variable of the current 
frame. The const is an immediate signed byte. The local variable at index must contain a 
short. The value const is first sign-extended to a short, then the local variable at index is 
incremented by that amount. 
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sine w 



Format 



Forms 
Stack 

Description 



Increment local short variable by constant 



sine w 



index 
bytel 



byte2 



sincjv = 150 (0x96) 



No change 



The index is an unsigned byte that must be a valid index into the local variable of the current 
frame. The immediate unsigned bytel and bytel values are assembled into a short const 
where the value of const is (bytel « 8) | byte2. The local variable at index, which must con- 
tain a short, is incremented by const. 
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sipush 



Push short 



Format 

Forms 
Stack 

Description 
Notes 



sipush 



bytel 
byte! 



sipush = 19(0x13) 



value J. word I, value!. word2 

The immediate unsigned bytel and byte2 values are assembled into a signed short where 
the value of the short is (bytel « 8) | byte2. The intermediate value is then sign-extended to 
an int, and the resulting value is pushed onto the operand stack. 

If a virtual machine does not support the int data type, the sipush instruction will not be 
available. 
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sload 



Load short from local variable 

Format ^ ^ 

sload 
index 

Forms 

sload = 22 (0x16) 

Stack 

... => 
value 

Description 

The index is an unsigned byte that must be a valid index into the local variables of the cur- 
rent frame. The local variable at index must contain a short. The value in the local variable 
at index is pushed onto the operand stack. 
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sload <n> 



Load short from local variable 



Format 
Forms 



Stack 



Description 



Notes 



sload <n> 



sload_0 = 2% (Oxlc) 
sload J = 29 (Oxld) 
sload_2 = 30 (Ox le) 
sloadj = 31(0x10 



value 



The <n> must be a valid index into the local variables of the current frame. The local vari- 
able at <n> must contain a short. The value in the local variable at <n> is pushed onto the 
operand stack. 

Each of the sload_<h> instructions is the same as sload with an index of <n>, except that 
the operand <n> is implicit. 
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slookupswitch 

Access jump table by key match and jump 

Format 

slookupswitch 
defaultbytel 
defaultbyte2 
npairsl 
npairsl 
match-offset pairs,.. 

Pair Format 

matchbytel 
matchbyte2 
offsetbytel 
offsetbyte2 



slookupswitch = 117 (0x75) 
Description 

A slookupswitch instruction is a variable-length instruction. Immediately after the slook- 
upswitch opcode follow a signed 16-bit value default, an unsigned 16-bit value npairs, and 
then npairs pairs. Each pair consists of a short match and a signed 16-bit offset. Each of 
the signed 16-bit values is constructed from two unsigned bytes as (bytel « 8) | bytel. 

The table match-offset pairs of the slookupswitch instruction must be sorted in increasing 
numerical order by match. 

The key must be of type short and is popped from the operand stack and compared against 
the match values. If it is equal to one of them, then a target address is calculated by adding 
the corresponding offset to the address of the opcode of this slookupswitch instruction. If the 
key does not match any of the match values, the target address is calculated by adding 
default to the address of the opcode of this slookupswitch instruction. Execution then con- 
tinues at the target address. 

The target address that can be calculated from the offset of each match-offset pair, as well as 
the one calculated from default, must be the address of an opcode of an instruction within 
the method that contains this slookupswitch instruction. 

Notes 

The match-offset pairs are sorted to support lookup routines that are quicker than linear 
search. 



Forms 
Stack 
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smul 



Multiply short 



Format 

Forms 

Stack 

Description 



smul 



smul = 69 (0x45) 

. . value! , value! ^> 
result 

Both valuel and value2 must be of type short. The values are popped from the operand 
stack. The short result is valuel * valuel. The result is pushed onto the operand stack. 

If a smul instruction overflows, then the result is the low-order bits of the mathematical 
product as a short. If overflow occurs, then the sign of the result may not be the same as 
the sign of the mathematical product of the two values. 
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sneg 



Negate short 



Format 

Forms 

Stack 

Description 



sneg 



sneg = 72 (0x4b) 

valuers 
result 

The value must be of type short. It is popped from the operand stack. The short result is 
the arithmetic negation of value, -value. The result is pushed onto the operand stack. 

For short values, negation is the same as subtraction from zero. Because the Java Card 
Virtual Machine uses two's-complement representation for integers and the range of two's- 
complement values is not symmetric, the negation of the maximum negative short results 
in that same maximum negative number. Despite the fact that overflow has occurred, no 
exception is thrown. 

For all short values x, -x equals (~x) + 1. 
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sor 



Boolean OR short 



Format 

Forms 

Stack 

Description 



sor 



sor = 85 (0x55) 

. . value I , value! => 
result 

Both value I and value2 must be of type short. The values are popped from the operand 
stack. A short result is calculated by taking the bitwise inclusive OR of valuel and value2. 
The result is pushed onto the operand stack. 
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srem 



Remainder short 



Format 

Forms 

Stack 

Description 



srem 



srem = 73 (0x49) 

value 1, value2: 
result 



Both value! and value2 must be of type short. The values are popped from the operand 
stack. The short result is the value of the Java expression valuel - {valuel I value!) * 
value2. The result is pushed onto the operand stack. 

The result of the irem instruction is such that ( a / b ) * b + ( a % b ) is equal to a . This iden- 
tity holds even in the special case that the dividend is the negative short of largest possible 
magnitude for its type and the divisor is -1 (the remainder is 0). It follows from this rule 
that the result of the remainder operation can be negative only if the dividend is negative 
and can be positive only if the dividend is positive. Moreover, the magnitude of the result is 
always less than the magnitude of the divisor. 

Runtime Exception 

If the value of the divisor for a short remainder operator is 0, srem throws an Arithmet- 
icException. 
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sreturn 

Format 

Forms 

Stack 

Description 



Return short from method 



sreturn 



sreturn = 120 (0x78) 



valuer 
[empty] 

The value must be of type short. It is popped from the operand stack of the current frame 
and pushed onto the operand stack of the frame of the invoker. Any other values on the 
operand stack of the current method are discarded. 

The virtual machine then reinstates the frame of the invoker and returns control to the 
invoker. 
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sshl 

Shift left short 

Format 

sshl 

Forms 

sshl = 77 (0x4d) 

Stack 

. . . , value I, value! => 
result 

Description 

Both valuel and value2 must be of type short. The values are popped from the operand 
stack. A short result is calculated by shifting valuel left by s bit positions, where s is the 
value of the low five bits of value2. The result is pushed onto the operand stack. 

Notes 

This is equivalent (even if overflow occurs) to multiplication by 2 to the power s. The shift 
distance actually used is always in the range 0 to 31, inclusive, as if value2 were subjected 
to a bitwise logical AND with the mask value Ox If. 



206 



Java Card Virtual Machine 2.1 Specification • January 29, 1999 



sshr 



Arithmetic shift right short 

Format ' 

sshr 

Forms 

sshr = 79 (0x4f) 

Stack 

. . ., value I, value2 ^> 
result 

Description 

Both valuel and value! must be of type short. The values are popped from the operand 
stack. A short result is calculated by shifting valuel right by s bit positions, with sign 
extension, where s. is the value of the low five bits of value2. The result is pushed onto the 
operand stack. 

Notes 

The resulting value is [.(valuel) I 2s X where s is value2 & Ox If. For nonnegative valuel, 
this is equivalent (even if overflow occurs) to truncating short division by 2 to the power 
s. The shift distance actually used is always in the range 0 to 31, inclusive, as if value2 were 
subjected to a bitwise logical AND with the mask value Ox If. 
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sspush 

Format 

Forms 
Stack 

Description 



Push short 



sspush 



bytel 



byte! 



sspush = 17(0x11) 

... => 
value 

The immediate unsigned bytel and byte2 values are assembled into a signed short where 
the value of the short is (bytel « 8) | bytel. The resulting value is pushed onto the operand 
stack. 
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sstore 



Store short into local variable 



Format 

Forms 
Stack 

Description 



sstore 



index 



sstore = 41 (0x29) 
value => 



The index is an unsigned byte that must be a valid index into the local variables of the cur- 
rent frame. The value on top of the operand stack must be of type short. It is popped from 
the operand stack, and the value of the local variable at index is set to value. 
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sstore_<n> 

Store short into local variable 

Format 

sstore <n> 



Forms 

sstore J) = 47 (0x2f) 
sstorej = 48 (0x30) 
sstorej = 49 (0x31) 
sstorej = 50 (0x32) 

Stack 

value => 



Description 

The <n> must be a valid index into the local variables of the current frame. The value on 
top of the operand stack must be of type short. It is popped from the operand stack, and 
the value of the local variable at <n> is set to value. 
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ssub 



Subtract short 



Format 

Forms 

Stack 

Description 



ssub 



ssub = 67 (0x43) 

value 7, value2^> 
result 

Both value 1 and value2 must be of type short. The values are popped from the operand 
stack. The short result is value! - valued The result is pushed onto the operand stack. 

For short subtraction, a - b produces the same result as a + (-b) . For short values, sub- 
traction from zeros is the same as negation. 

Despite the fact that overflow or underflow may occur, in which case the result may have a 
different sign than the true mathematical result, execution of a ssub instruction never throws 
a runtime exception. 



Chapter 7 



Java Card Virtual Machine Instruction Set 211 



stableswitch 

Access jump table by short index and jump 

Format 

stableswitch 
defaultbytel 
defaultbyte2 

lowbytel 

lowbyte2 

highbytel 

highbyte2 
jump offsets,.. 

Offset Format 

offsetbytel 
offsetbytel 



stableswitch = 115 (0x73) 
index 
Description 

A stableswitch instruction is a variable-length instruction. Immediately after the sta- 
bleswitch opcode follow a signed 16-bit value default, a signed 16-bit value low, a signed 
16-bit value high, and then high - low + 1 further signed 16-bit offsets. The value low must 
be less than or equal to high. The high - low + 1 signed 16-bit offsets are treated as a 0- 
based jump table. Each of the signed 1 6-bit values is constructed from two unsigned bytes 
as (byte J « 8) | byte2. 

The index must be of type short and is popped from the stack. If index is less than low or 
index is greater than high, than a target address is calculated by adding default to the 
address of the opcode of this stableswitch instruction. Otherwise, the offset at position index 
- low of the jump table is extracted. The target address is calculated by adding that offset to 
the address of the opcode of this stableswitch instruction. Execution then continues at the 
target address. 

The target addresses which can be calculated from each jump table offset, as well as the one 
calculated from default, must be the address of an opcode of an instruction within the 
method that contains this stableswitch instruction. 



Forms 
Stack 



212 Java Card Virtual Machine 2.1 Specification • January 29, 1999 



4 



sushr 

Logical shift right short 

Format 

sushr 

Forms 

sushr = 81 (0x51) 

Stack 

value 1, value2^> 
result 

Description 

Both valuel and value2 must be of type short. The values are popped from the operand 
stack. A short result is calculated by sign-extending valuel to 32 bits and shifting the 
result right by s bit positions, with zero extension, where s is the value of the low five bits of 
value2. The result is pushed onto the operand stack. 

Notes 

If valuel is positive and s is value2 & 0x1 f, the result is the same as that of valuel » s; if 
valuel is negative, the result is equal to the value of the expression (valuel » s) + (2 « 
The addition of the (2 « ~s) term cancels out the propagated sign bit. The shift dis- 
tance actually used is always in the range 0 to 3 1, inclusive, as if value2 were subjected to a 
bitwise logical AND with the mask value Ox If. 
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swapx 

Format 

Forms 
Stack 

Description 



Notes 



Swap top two operand stack words 



swapjc 



mn 



swapjc ~ 64 (0x40) 

. . ., wordM+N, . . ., wordM+U wordM, . . wordl ^> 
wordM, word], wordM+N, wordM+1 

The unsigned byte mn is used to construct two parameter values. The high nybble, {mn & 
OxfO) » 4, is used as the value m. The low nybble, {mn & Oxf), is used as the value n. Per- 
missible values for both m and n are 1-4. 

The top m words on the operand stack are swapped with the n words immediately below. 

The swapjc instruction must not be used unless the ranges of words 1 through m and words 
7H+1 through n each contain either a 16-bit data type, two 16-bit data types, a 32-bit data 
type, a 16-bit data type and a 32-bit data type (in either order), or two 32-bit data types. 

Except for restrictions preserving the integrity of 32-bit data types, the swap x instruction 
operates on untyped words, ignoring the types of data they contain. 

If a virtual machine does not support the int data type, the permissible values for both m 
and n are 1 or 2. 
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sxor 



Boolean XOR short 

Format 

sxor 

Forms 

sxor = 87 (0x57) 

Stack 

valuel, value2^> 
result 

Description 

Both value! and value2 must be of type short. The values are popped from the operand 
stack. A short result is calculated by taking the bitwise exclusive OR of value! and 
value!. The result is pushed onto the operand stack. 
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CHAPTER 



Tables of Instructions 



TABLE 8-1 Instructions by Opcode Value 



0 
1 
2 
3 
4 
5 
6 
7 
8 
9 
10 
11 
12 
13 
14 
15 
16 
17 
18 
19 
20 
21 
22 
23 
24 
25 
26 
27 
28 
29 
30 
31 
32 
33 
34 
35 
36 
37 
38 
39 
40 
41 
42 
43 
44 
45 
46 



nop 

aconst_null 

sconst_m1 

sconst_0 

sconsM 

sconst_2 

sconst_3 

sconst_4 

sconst_5 

iconst_m1 

iconst_0 

iconsM 

iconst_2 

iconst_3 

iconst_4 

iconst_5 

bspush 

sspush 

bipush 

sipush 

iipush 

aload 

sload 

iload 

aload_0 

aload_1 

aload_2 

aload_3 

sload_0 

sload_1 

sload_2 

sload_3 

iload_0 

iload_1 

iload_2 

iload_3 

aatoad 

baload 

saload 

iaload 

astore 

sstore 

istore 

astore_0 

astore_1 

astore_2 

astore 3 



47 sstore_0 

48 sstore_1 

49 sstore 2 

50 sstore_3 

51 istore_0 

52 istore_1 

53 istore_2 

54 istore^3 

55 aastore 

56 bastore 

57 sastore 

58 iastore 

59 pop 

60 pop2 

61 dup 

62 dup2 

63 dup_x 

64 swap_x 

65 sadd 

66 iadd 

67 ssub 

68 isub 

69 smul 

70 imul 

71 sdiv 

72 idiv 

73 srem 

74 irem 

75 sneg 

76 ineg 

77 sshl 

78 ishl 

79 sshr 

80 ishr 

81 sushr 

82 iushr 

83 sand 

84 iand 

85 sor 

86 ior 

87 sxor 

88 ixor 

89 sine 

90 iinc 

91 s2b 

92 s2i 

93 i2b 



94 
95 
96 
97 
98 
99 
100 
101 
102 
103 
104 
105 
106 
107 
108 
109 
110 
111 
112 
113 
114 
115 
116 
117 
118 
119 
120 
121 
122 
123 
124 
125 
126 
127 
128 
129 
130 
131 
132 
133 
134 
135 
136 
137 
138 
139 
140 



i2s 

icmp 

ifeq 

ifne 

iflt 

ifge 

ifgt 

ifle 

ifnull 

ifhonnull 

if_acmpeq 

if acmpne 

iCscmpeq 

if scmpne 

if scmplt 

iCscmpge 

if_scmpgt 

if_scmple 

goto 

jsr 

ret 

stableswitch 

itableswitch 

slookupswitch 

ilookupswitch 

aretum 

sretum 

ireturn 

return 

getstatic_a 

getstaticj) 

getstatic_s 

getstaticj 

putstatic a 

putstatic~b 

putstatic_s 

putstaticj 

getfield_a 

getfield_b 

getfield_s 

getfieldj 

putfield_a 

putfie(d_b 

putfield_s 

putfieldj 

invokevlrtual 

invokespecial 



141 invokestatic 

142 invokeinterface 

143 new 

144 newarray 

145 anewarray 

146 arraylength 

147 athrow 

148 checkcast 

149 instanceof 

150 sinc_w 

151 iinc_w 

152 ifeq_w 

153 ifne_w 

154 iflt_w 

155 ifge_w 

156 ifgt_w 

157 iflejv 

158 ifhull_w 

159 ifhonnu!l_w 

160 if acmpeq_w 

161 if" acmpnej/v 

162 if" scmpeq_w 

163 if" scmpne_w 

164 if" scmplt_w 

165 if scmpge_w 

166 if" scmpgt_w 

167 iCscmple_w 

168 goto_w 

169 getfield_a w 

170 getfieldjTw 

171 getfield_s_w 

172 getfieldj_w 

173 getfield_a_this 

174 getfield_b_this 

175 getfield_s_this 

176 getfieldj Jhis 

1 77 putfield_alw 

1 78 putfield_b_w 

179 putfield_s_w 

180 putfieldj_w 

181 putfield_a_this 

182 putfieldj) Jhis 

183 putfield_sjhis 

184 putfieldj Jhis 

254 impdepl 

255 impdep2 



TABLE 8-2 Instructions by Opcode Mnemonic 



aaload 

aastore 

aconst_null 

aload 

aload_0 

aload_1 

aload_2 

a!oad_3 

anewarray 

aretum 

arraylength 

astore 

astore_0 

astore_1 

astore_2 

astore_3 

athrow 

baload 

bastore 

bipush 

bspush 

checkcast 

dup 

dup_x 

dup2 

getfield_a 

getfield_a_this 

getfield_a_w 

getfield_b 

getfield_b_this 

getfield_b_w 

getfieldj 

getfieldj_this 

getfield_i_w 

getfield_s 

getfield_s_this 

getfield_s_w 

getstatic_a 

getstatic_b 

getstatic_i 

getstatic_s 

goto 

goto w 

i2b " 

i2s 

iadd 

iaload 



36 
55 
1 
21 
24 
25 
26 
27 
145 
119 
146 
40 
43 
44 
45 
46 
147 
37 
56 
18 
16 
148 
61 
63 
62 
131 
173 
169 
132 
174 
170 
134 
176 
172 
133 
175 
171 
123 
124 
126 
125 
112 
168 
93 
94 
66 
39 



iastore 
icmp 
iconst_0 
iconsM 
iconst_2 
iconst~3 
iconst_4 
iconst_5 
iconst_m1 
idiv 

if acmpeq 

iCacmpeq_w 

if acmpne 

if" acmpne_w 

iCscmpeq 

if_scmpeq_w 

if_scmpge 

if_scmpge_w 

if_scmpgt 

if scmpgt_w 

iCscmple 

if_scmple_w 

if scmplt 

irscmplt_w 

if_scmpne 

if scmpne_w 

ifeq 

ifeq_w 

ifge 

ifgej/v 

ifgt 

ifgt_w 

ifle 

ifle_w 
iflt 

iflt_w 

ifne 

ifne_w 

ifnonnuli 

ifnonnull_w 

ifnull 

ifnull_w 

iinc 

iinc_w 

iipush 

iload 



iand 



84 
58 
95 
10 
11 
12 
13 
14 
15 
9 
72 
104 
160 
105 
161 
106 
162 
109 
165 
110 
166 
111 
167 
108 
164 
107 
163 
96 
152 
99 
155 
100 
156 
101 
157 
98 
154 
97 
153 
103 
159 
102 
158 
90 
151 
20 
23 



iloadj) 

iload_1 

iload_2 

iload_3 

ilookupswitch 

imul 

ineg 

instanceof 

invokeinterface 

invokespecial 

invokestatic 

invokevirtual 

ior 

irem 

ireturn 

isht 

ishr 

istore 

istorej) 

istore_1 

istore_2 

istore_3 

isub 

itableswitch 

iushr 

ixor 

jsr 

new 

newarray 
nop 
pop 
pop2 

putfield_a 

putfield_a_this 

putfield_a_w 

putfield_b 

putfield_b_this 

putfield_b_w 

putfieldj 

putfield_i_this 

putfield_i_w 

putfield_s 

putfield_s_this 

putfield_s_w 

putstatic_a 

putstatic_b 

putstaticj 







19Q 


00 


rpt 


114 


J4 


return 


199 


QE. 
OD 


SZD 


Q1 


no 


S^l 




7 U 


sadd 


fit; 

DO 


7C 

7o 


saload 


00 


i4y 


sand 


00 


14z 


sastore 


Of 


14U 


sconsi_u 


O 


4 A 4 


sconst_1 


A 

4 




sconst_2 


c 
D 


00 


sconst_3 


O 




sconst_4 






sconst_5 


Q 
O 


7A 


sconsi_m 1 


O 
£. 


Qf\ 

oU 


sdiv 


-T4 

f\ 


42 


sine 


on 

oy 


51 


sinc_w 


15U 


CO 

Od 


sipush 


iy 


CO 

53 


sioad 




54 


sload_o 




DO 


sioaa_i 


on 

zy 


no 


sload_2 


oU 


OZ 


sioaa_o 


0 I 


OO 


si 00 k u ps wiicn 


117 


113 


smut 


69 


143 


sneg 


75 


144 


sor 


85 


0 


srem 


73 


59 


sretum 


120 


60 


sshl 


77 


135 


sshr 


79 


181 


sspush 


17 


177 


sstore 


41 


136 


sstorej) 


47 


182 


sstore_1 


48 


178 


sstore_2 


49 


138 


sstore_3 


50 


184 


ssub 


67 


180 


stableswitch 


115 


137 


sushr 


81 


183 


swap_x 


64 


179 


sxor 


87 



127 
128 
130 



218 Java Card Virtual Machine 2.1 Specification • January 29, 1999 



Glossary 



AID is an acronym for Application IDentifier as defined in ISO 7816-5. 

APDU is an acronym for Application Protocol Data Unit as defined in ISO 7816-4. 

API is an acronym for Application Programming Interface. The API defines calling 
conventions by which an application program accesses the operating system and other 
services. 

Applet the basic unit of selection, context, functionality, and security in Java Card 
technology. 

Applet developer refers to a person creating a Java Card applet using the Java Card 
technology specifications. 

Applet context. The JCRE keeps track of the currently selected Java Card applet as well as 
the currently active Java Card applet. The currently active Java Card applet value is referred 
to as the Java Card applet context. When an instance method is invoked on an object, the 
Java Card applet execution context is changed to correspond to the Java Card applet that 
owns that object. When that method returns, the previous context is restored. Invocations of 
static methods have no effect on the Java Card applet execution context. The Java Card 
applet context and sharing status of an object together determine if access to an object is 
permissible. 

Atomic operation is an operation that either completes in its entirety (if the operation 
succeeds) or no part of the operation completes at all (if the operation fails). 

Atomicity refers to whether a particular operation is atomic or not and is necessary for 
proper data recovery in cases where power is lost or the card is unexpectedly removed from 
the CAD. 

ATR is an acronym for Answer to Reset. An ATR is a string of bytes sent by the Java Card 
after a reset condition. 

CAD is an acronym for Card Acceptance Device. The CAD is the device in which the card 
is inserted. 
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Cast is the explicit conversion from one data type to another. 

cJCK is a test suite to verify the compliance of the implementation of the Java Card 
Technology specifications. The cJCK uses the JavaTest tool to run the test suite. 

Class is the prototype for an object in an object-oriented language. A class may also be 
considered a set of objects which share a common structure and behavior. The structure of a 
class is determined by the class variables which represent the state of an object of that class 
and the behavior is given by a set of methods associated with the class. 

Classes are related in a class hierarchy. One class may be a specialization (a "subclass") of 
another (one of its "superclasses"), it may be composed of other classes, or it may use other 
classes in a client-server relationship. 

EEPROM is an acronym for Electrically Erasable, Programmable Read Only Memory. 

EMV is an acronym for Europay, MasterCard, and Visa. EMV is used to refer to the ICC 
specifications for payment systems. 

Framework is the set of classes which implement the API. This includes core and 
extension packages. Responsibilities include dispatching of APDUs, applet selection, 
managing atomicity, and installing applets. 

Garbage collection is the process by which dynamically allocated storage is automatically 
reclaimed during the execution of a program. 

GUI is an acronym for Graphical User Interface. The GUI provides application control 
through the use of graphic images. 

ICC is an acronym for Integrated Circuit Card. 

IDE acronym for Interactive Development Environment. An IDE is a system for supporting 
the process of writing software which may include a syntax-directed editor, graphical tools 
for program entry, and integrated support for compiling the program and relating compilation 
errors back to the source. 

Instance variables, also known as fields, represent a portion of an object's internal state. 
Each object has its own set of instance variables. Objects of the same class will have the 
same instance variables, but each object can have different values. 

Instantiation, in object-oriented programming, means to produce a particular object from its 
class template. This involves allocation of a data structure with the types specified by the 
template, and initialization of instance variables with either default values or those provided 
by the class's constructor function. 

JAR is an acronym for Java Archive. JAR is a platform-independent file format that 
combines many files into one. 

Java Card Runtime Environment (JCRE) consists of the Java Card Virtual Machine, the 
framework, and the associated native methods. 
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JC20RI is an acronym for the Java Card 2.0 Reference Implementation. 

JCRE implementer refers to a person creating a vendor-specific framework using the Java 
Card 2.0 API. 

JCVM is an acronym for the Java Card Virtual Machine. The JCVM is the foundation of the 
OP card architecture. The JCVM executes byte code and manages classes and objects. It 
enforces separation between applications (firewalls) and enables secure data sharing. 

JDK is an acronym for Java Development Kit. The JDK is a Sun Microsystems, Inc. product 
which provides the environment required for programming in Java. The JDK is available for 
a variety of platforms, but most notably Sun Solaris and Microsoft Windows®. 

MAC is an acronym for Message Authentication Code. MAC is an encryption of data for 
security purposes. 

Method is the name given to a procedure or routine, associated with one or more classes, in 
object-oriented languages. 

Namespace is a set of names in which all names are unique. 

Object-Oriented is a programming methodology based on the concept of an "object" which 
is a data structure encapsulated with a set of routines, called "methods," which operate on the 
data. 

Objects, in object-oriented programming, are unique instances of a data structure defined 
according to the template provided by its class. Each object has its own values for the 
variables belonging to its class and can respond to the messages (methods) defined by its 
class. 

Package is a namespace within the Java programming language and can have classes and 
interfaces. A package is the smallest unit within the Java programming language. 

Persistent object. Persistent objects and their values persist from one CAD session to the 
next, indefinitely. Objects are persistent by default. Persistent object values are updated 
atomically using transactions. The term persistent does not mean there is an object-oriented 
database on the card or that objects are serialized/deserialized, just that the objects are not 
lost when the card loses power. 

PSE is an acronym for Payment System Environment as described by the EMV specification. 

System configuration refers to the combination of operating system platform and Java 
programming language tools. 

TCL is an acronym for Tool Command Language. For more information on TCL, access the 
following URL: http2.brunel.ac.uk:8080/-<sstddm/TCL2/TCL2.html. 

Transaction is an atomic operation where the developer defines the extent of the operation 
by indicating in the program code the beginning and end of the transaction. 
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Transient object. The values of transient objects do not persist from one CAD session to the 
next, and are reset to a default state at specified intervals. Updates to the values of transient 
objects are not atomic and are not effected by transactions. 



222 



Java Card Virtual Machine 2.1 Specification • January 29, 1999 



